Fix clippy and doc test errors

develop changed every sequence-based `keylet::` factory to take
`SeqProxy const&` instead of `std::uint32_t`, and removed the
two-argument `mptokenIssuance(seq, issuer)` overload. The wasm host
functions and their tests still passed raw sequences, so the branch
merged cleanly but did not compile.

Wrap the raw sequences at the call sites, matching the idiom develop
adopted in its own tests:

- `SeqProxy::rawSequence` for check, escrow, nftokenOffer, offer,
  payChannel, permissionedDomain and vault
- `SeqProxy::rawTicket` for ticket
- `keylet::mptokenIssuance(makeMptID(seq, issuer))` for the removed
  overload

No computed keylet changes: the factories only read `seq.value()`, and
the removed overload was itself defined as `mptokenIssuance(makeMptID(
seq, issuer))`.

.codecov.yml

@@ -58,13 +58,3 @@ ignore:
   - "src/tests/"
   - "include/xrpl/beast/test/"
   - "include/xrpl/beast/unit_test/"
-  # Telemetry modules — conditionally compiled behind XRPL_ENABLE_TELEMETRY,
-  # which is not enabled in coverage builds.
-  - "src/xrpld/telemetry/"
-  - "src/libxrpl/telemetry/"
-  - "include/xrpl/telemetry/"
-  - "src/libxrpl/beast/insight/OTelCollector.cpp"
-  - "include/xrpl/beast/insight/OTelCollector.h"
-  # Per-module span-name constant headers (compile-time constants only,
-  # colocated with their subsystem rather than under telemetry/).
-  - "**/*SpanNames.h"

.cspell.config.yaml

@@ -7,7 +7,6 @@ ignorePaths:
   - cmake/**
   - LICENSE.md
   - .clang-tidy
-  - nix/check-tools/*.txt # generated, and full of Nix store hashes
 language: en
 allowCompoundWords: true # TODO (#6334)
 ignoreRandomStrings: true
@@ -19,7 +18,6 @@ dictionaries:
 ignoreRegExpList:
   - /\b[rs][1-9A-HJ-NP-Za-km-z]{25,34}/g # addresses and seeds
   - /\bC[A-Z0-9]{15}/g # CTIDs
-  - /\bXRPL_METRIC_[A-Z_]+/g # telemetry macro names; the splitter emits subwords like ISTOGRAM
   - /\b(XRPL|BEAST)_[A-Z_0-9]+_H_INCLUDED+/g # include guards
   - /\b(XRPL|BEAST)_[A-Z_0-9]+_H+/g # include guards
   - /::[a-z:_]+/g # things from other namespaces
@@ -69,9 +67,8 @@ words:
   - Btrfs
   - Buildx
   - canonicality
-  - CGNAT
+  - cdylib
   - canonicalised
-  - cctools
   - changespq
   - checkme
   - choco
@@ -104,29 +101,24 @@ words:
   - dearmor
   - decryptor
   - dedented
-  - Dedup
-  - dedup
   - deleteme
   - demultiplexer
   - deserializaton
+  - desugars
   - desync
   - desynced
   - determ
   - disablerepo
   - distro
   - doxyfile
-  - dsymutil
-  - dthms
   - dxrpl
   - elgamal
   - enabled
   - enablerepo
   - endmacro
   - envrc
-  - EOCFG
   - exceptioned
   - EXPECT_STREQ
-  - exfiltration
   - Falco
   - fcontext
   - finalizers
@@ -135,23 +127,20 @@ words:
   - fsanitize
   - funclets
   - Gamal
-  - gantt
-  - Gantt
   - gcov
   - gcovr
   - ghead
+  - gmock
   - Gnutella
   - godexsoft
   - gpgcheck
   - gpgkey
-  - havetxset
   - Hinnant
   - hotwallet
-  - hicpp
-  - htpasswd
   - hwaddress
   - hwrap
   - ifndef
+  - impls
   - inequation
   - initialiser
   - insuf
@@ -164,7 +153,6 @@ words:
   - itype
   - jemalloc
   - jlog
-  - jmeter
   - jtnofill
   - keylet
   - keylets
@@ -182,20 +170,19 @@ words:
   - libxrpl
   - llection
   - LOCALGOOD
-  - logql
   - logwstream
   - Lombrozo
-  - lresolv
   - lseq
   - lsmf
   - ltype
   - mathbunnyru
   - mcmodel
   - MEMORYSTATUSEX
+  - MPTAMM
+  - MPTDEX
   - Merkle
   - misprediction
   - missingok
-  - MPTAMM
   - mptbalance
   - MPTDEX
   - mptflags
@@ -225,13 +212,11 @@ words:
   - nixfmt
   - nixos
   - nixpkgs
-  - NETOP
   - NOLINT
   - NOLINTNEXTLINE
   - nonxrp
   - noreplace
   - noripple
-  - nostd
   - nostdinc
   - notifempty
   - nudb
@@ -240,9 +225,6 @@ words:
   - Nyffenegger
   - onlatest
   - ostr
-  - otelc
-  - otelcol
-  - otool
   - oxalica
   - pargs
   - partitioner
@@ -252,12 +234,8 @@ words:
   - permdex
   - perminute
   - permissioned
-  - pgrep
-  - pkill
-  - pimpl
   - pointee
   - populator
-  - pratik
   - preauth
   - preauthorization
   - preauthorize
@@ -272,22 +250,16 @@ words:
   - pyparsing
   - qalloc
   - qbsprofile
+  - qself
   - queuable
-  - ransitioned
   - Raphson
   - rcflags
-  - reparent
   - replayer
-  - repodata
-  - repomd
-  - reqps
   - rerandomize
   - rerandomization
   - rerandomized
   - rerandomizes
   - rerere
-  - retargeted
-  - retargets
   - retriable
   - RIPD
   - ripdtop
@@ -304,11 +276,6 @@ words:
   - rustfmt
   - rustup
   - sahyadri
-  - sanitisation
-  - sanitise
-  - sanitised
-  - sanitiser
-  - sanitising
   - Satoshi
   - scons
   - Schnorr
@@ -328,8 +295,6 @@ words:
   - sles
   - soci
   - socidb
-  - Sonatype
-  - speciality
   - sponsee
   - sponsees
   - SRPMS
@@ -337,8 +302,8 @@ words:
   - statsd
   - STATSDCOLLECTOR
   - stissue
-  - stledgerentry
   - stnum
+  - stnumber
   - stobj
   - stobject
   - stpath
@@ -351,14 +316,12 @@ words:
   - superpeer
   - superpeers
   - Swatinem
-  - synthesise
   - takergets
   - takerpays
   - ters
   - TMEndpointv2
   - toolchain
   - tparam
-  - traceql
   - trixie
   - tx
   - txid
@@ -366,9 +329,7 @@ words:
   - txjson
   - txn
   - txns
-  - txqueue
   - txs
-  - txset
   - ubsan
   - UBSAN
   - ufdio
@@ -382,8 +343,8 @@ words:
   - unfindable
   - unflatten
   - unfund
-  - unheld
   - unimpair
+  - unmetered
   - unroutable
   - unscalable
   - unserviced
@@ -393,20 +354,18 @@ words:
   - unsquelch
   - unsquelched
   - unsquelching
-  - unstored
   - unsuffixed
   - unvalidated
   - unveto
   - unvetoed
   - upvotes
   - USDB
-  - utilisation
   - variadics
   - venv
   - vfalco
   - vinnie
   - wasmi
-  - werror
+  - Werror
   - wextra
   - wptr
   - writeme
@@ -414,18 +373,13 @@ words:
   - wthread
   - xbridge
   - xchain
-  - xcrun
+  - xfloat
   - ximinez
   - XMACRO
-  - xored
   - xrpkuwait
   - xrpl
   - xrpld
   - xrplf
   - xxhash
   - xxhasher
-  - xychart
-  - zpages
-  - zstdio
-  - ripplex
-  - mseconds
+  - CGNAT

.envrc

@@ -1,7 +1,3 @@
 watch_file nix/*.nix
 
-# The dev shell derivation includes all of conan/ (see nix/devshell.nix), so any
-# change in there has to invalidate direnv's cached environment.
-watch_dir conan
-
 use flake

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

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

.github/actions/release-info/action.yml

@@ -1,90 +0,0 @@
-name: Release info
-description: "Derive the version, release channel and package release number for this build."
-
-outputs:
-  version:
-    description: "The build version number."
-    value: ${{ steps.version.outputs.version }}
-  channel:
-    description: "The release channel this build belongs to."
-    value: ${{ steps.channel.outputs.channel }}
-  pkg_release:
-    description: "The package release number: 1 for a tag, the run number otherwise."
-    value: ${{ steps.pkg_release.outputs.pkg_release }}
-
-runs:
-  using: composite
-  steps:
-    # A tag names its own version. Anything else takes it from BuildInfo.cpp and
-    # appends the commit hash as build metadata, joined with a plus sign because a
-    # Conan version cannot contain two hyphens.
-    - name: Determine version
-      id: version
-      shell: bash
-      env:
-        IS_TAG: ${{ startsWith(github.ref, 'refs/tags/') }}
-        REF_NAME: ${{ github.ref_name }}
-        SHA: ${{ github.sha }}
-      run: |
-        if [[ "${IS_TAG}" == "true" ]]; then
-            version="${REF_NAME}"
-        else
-            version="$(awk -F'"' '/versionString =/ { print $2 }' src/libxrpl/protocol/BuildInfo.cpp)"
-            if [[ -z "${version}" ]]; then
-                echo "Unable to read versionString from BuildInfo.cpp." >&2
-                exit 1
-            fi
-            version="${version}+${SHA:0:7}"
-        fi
-
-        echo "version=${version}" | tee -a "${GITHUB_OUTPUT}"
-
-    # Only a tag says how mature a build is: a push is a develop build whatever
-    # its version, and a non-public codebase keeps its packages to itself.
-    - name: Determine release channel
-      id: channel
-      shell: bash
-      env:
-        IS_TAG: ${{ startsWith(github.ref, 'refs/tags/') }}
-        REF_NAME: ${{ github.ref_name }}
-        VISIBILITY: ${{ github.event.repository.visibility }}
-      run: |
-        pre_release=""
-        if [[ "${REF_NAME}" == *-* ]]; then
-            pre_release="${REF_NAME#*-}"
-        fi
-
-        if [[ "${VISIBILITY}" != "public" ]]; then
-            channel=private
-        elif [[ "${IS_TAG}" != "true" ]]; then
-            channel=develop
-        elif [[ -z "${pre_release}" ]]; then
-            channel=stable
-        elif [[ "${pre_release}" =~ ^rc[0-9]+(\+.*)?$ ]]; then
-            channel=unstable
-        elif [[ "${pre_release}" =~ ^b(0|[1-9][0-9]*)(\+.*)?$ ]]; then
-            channel=experimental
-        else
-            echo "Unsupported pre-release in tag '${REF_NAME}'. Use bN or rcN." >&2
-            exit 1
-        fi
-
-        echo "channel=${channel}" | tee -a "${GITHUB_OUTPUT}"
-
-    # A tag is packaged once, so its release number is fixed at 1. Develop builds
-    # repeat the same version, so the run number is what makes each push an
-    # upgrade rather than a reinstall.
-    - name: Determine package release
-      id: pkg_release
-      shell: bash
-      env:
-        IS_TAG: ${{ startsWith(github.ref, 'refs/tags/') }}
-        RUN_NUMBER: ${{ github.run_number }}
-      run: |
-        if [[ "${IS_TAG}" == "true" ]]; then
-            pkg_release=1
-        else
-            pkg_release="${RUN_NUMBER}"
-        fi
-
-        echo "pkg_release=${pkg_release}" | tee -a "${GITHUB_OUTPUT}"

.github/actions/setup-nix-env/action.yml

@@ -1,69 +0,0 @@
-name: Setup Nix environment
-description: "Build the flake's CI environment and put its tools on PATH."
-
-# The environment from nix/ci-env.nix, the same one the Linux CI images bake in
-# (see nix/docker). Exported onto PATH rather than entered with `nix develop`:
-# the composite actions below run plain `bash` and would escape a dev shell.
-
-runs:
-  using: composite
-
-  steps:
-    - name: Build the CI environment
-      id: build
-      shell: bash
-      env:
-        # --out-link doubles as a GC root for the length of the job.
-        OUT_LINK: ${{ runner.temp }}/xrpld-ci-env
-      run: |
-        # --extra-experimental-features: flakes may not be on in the runner's nix.conf.
-        nix --extra-experimental-features "nix-command flakes" \
-            build .#default --out-link "${OUT_LINK}" --print-build-logs
-        echo "path=$(readlink -f "${OUT_LINK}")" >>"${GITHUB_OUTPUT}"
-
-    - name: Export the environment
-      shell: bash
-      env:
-        ENV_PATH: ${{ steps.build.outputs.path }}
-      run: |
-        echo "${ENV_PATH}/bin" >>"${GITHUB_PATH}"
-
-        # Already KEY=VALUE per line. See `darwinEnv` in nix/ci-env.nix.
-        ENV_FILE="${ENV_PATH}/share/xrpld-ci-env/env"
-        if [ -f "${ENV_FILE}" ]; then
-            cat "${ENV_FILE}" >>"${GITHUB_ENV}"
-        fi
-
-        # XrplSanity.cmake otherwise rejects a Nix compiler as one that leaked.
-        echo "XRPL_DEVSHELL=ci-env" >>"${GITHUB_ENV}"
-
-        # Unlike the Linux nix images, macOS needs no SSL_CERT_FILE: it has its
-        # own trust store, and pinning would break TLS to hosts relying on it.
-
-        # Workspace-local, so `cleanup-workspace` clears it, but not the
-        # `.conan2` prepare-runner hands the system toolchain: that Conan is a
-        # different version, and the two would migrate each other's cache.
-        echo "CONAN_HOME=${{ github.workspace }}/.conan2-nix" >>"${GITHUB_ENV}"
-
-    # Config, profiles and remote, exactly as the dev shell sets them up on
-    # entry; the `setup-conan` action is skipped for this toolchain.
-    - name: Setup Conan
-      shell: bash
-      run: ./conan/init.sh
-
-    # `Check tools` runs later but swallows failures; a bad export would just
-    # build with the system toolchain.
-    - name: Verify the toolchain resolves into the Nix store
-      shell: bash
-      run: |
-        for tool in clang clang++ cmake ninja conan; do
-            path="$(command -v "${tool}" || true)"
-            echo "${tool} -> ${path:-<not found>}"
-            case "${path}" in
-                /nix/store/*) ;;
-                *)
-                    echo "::error::${tool} does not resolve into the Nix store"
-                    exit 1
-                    ;;
-            esac
-        done

.github/dependabot.yml

@@ -4,7 +4,7 @@ updates:
     directories:
       - /
       - .github/actions/build-deps/
-      - .github/actions/release-info/
+      - .github/actions/generate-version/
       - .github/actions/set-compiler-env/
       - .github/actions/setup-conan/
     schedule:
@@ -28,9 +28,10 @@ updates:
       time: "04:00"
       timezone: Etc/GMT
     commit-message:
-      prefix: "chore: [DEPENDABOT] "
+      prefix: "ci: [DEPENDABOT] "
     target-branch: develop
     open-pull-requests-limit: 10
+    # Bundle all Rust dependency bumps into a single PR per run to reduce noise.
     groups:
       rust-dependencies:
         patterns:

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

@@ -7,12 +7,6 @@ Loop: xrpld.app xrpld.rpc
 Loop: xrpld.app xrpld.shamap
   xrpld.shamap > xrpld.app
 
-Loop: xrpld.app xrpld.telemetry
-  xrpld.app > xrpld.telemetry
-
 Loop: xrpld.overlay xrpld.rpc
   xrpld.rpc ~= xrpld.overlay
 
-Loop: xrpld.overlay xrpld.telemetry
-  xrpld.overlay > xrpld.telemetry
-

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

@@ -53,10 +53,6 @@ libxrpl.shamap > xrpl.basics
 libxrpl.shamap > xrpl.nodestore
 libxrpl.shamap > xrpl.protocol
 libxrpl.shamap > xrpl.shamap
-libxrpl.telemetry > xrpl.basics
-libxrpl.telemetry > xrpl.config
-libxrpl.telemetry > xrpl.protocol
-libxrpl.telemetry > xrpl.telemetry
 libxrpl.tx > xrpl.basics
 libxrpl.tx > xrpl.conditions
 libxrpl.tx > xrpl.core
@@ -64,7 +60,6 @@ libxrpl.tx > xrpl.json
 libxrpl.tx > xrpl.ledger
 libxrpl.tx > xrpl.protocol
 libxrpl.tx > xrpl.server
-libxrpl.tx > xrpl.telemetry
 libxrpl.tx > xrpl.tx
 test.app > test.jtx
 test.app > test.unit_test
@@ -135,12 +130,8 @@ test.ledger > xrpl.json
 test.ledger > xrpl.ledger
 test.ledger > xrpl.protocol
 test.nodestore > test.jtx
-test.nodestore > test.unit_test
 test.nodestore > xrpl.basics
-test.nodestore > xrpl.config
-test.nodestore > xrpld.app
 test.nodestore > xrpld.core
-test.nodestore > xrpld.telemetry
 test.nodestore > xrpl.nodestore
 test.nodestore > xrpl.rdb
 test.overlay > test.jtx
@@ -192,9 +183,6 @@ tests.libxrpl > xrpl.basics
 tests.libxrpl > xrpl.config
 tests.libxrpl > xrpl.consensus
 tests.libxrpl > xrpl.core
-tests.libxrpl > xrpld.app
-tests.libxrpl > xrpld.overlay
-tests.libxrpl > xrpld.telemetry
 tests.libxrpl > xrpl.json
 tests.libxrpl > xrpl.ledger
 tests.libxrpl > xrpl.net
@@ -205,7 +193,6 @@ tests.libxrpl > xrpl.protocol_autogen
 tests.libxrpl > xrpl.resource
 tests.libxrpl > xrpl.server
 tests.libxrpl > xrpl.shamap
-tests.libxrpl > xrpl.telemetry
 tests.libxrpl > xrpl.tx
 xrpl.conditions > xrpl.basics
 xrpl.conditions > xrpl.protocol
@@ -214,7 +201,6 @@ xrpl.consensus > xrpl.basics
 xrpl.consensus > xrpl.json
 xrpl.consensus > xrpl.ledger
 xrpl.consensus > xrpl.protocol
-xrpl.consensus > xrpl.telemetry
 xrpl.core > xrpl.basics
 xrpl.core > xrpl.json
 xrpl.core > xrpl.protocol
@@ -250,13 +236,10 @@ xrpl.server > xrpl.resource
 xrpl.shamap > xrpl.basics
 xrpl.shamap > xrpl.nodestore
 xrpl.shamap > xrpl.protocol
-xrpl.telemetry > xrpl.basics
-xrpl.telemetry > xrpl.config
 xrpl.tx > xrpl.basics
 xrpl.tx > xrpl.core
 xrpl.tx > xrpl.ledger
 xrpl.tx > xrpl.protocol
-xrpl.tx > xrpl.telemetry
 xrpld.app > test.unit_test
 xrpld.app > xrpl.basics
 xrpld.app > xrpl.config
@@ -273,7 +256,6 @@ 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.core > xrpl.basics
 xrpld.core > xrpl.config
@@ -294,7 +276,6 @@ xrpld.overlay > xrpl.protocol
 xrpld.overlay > xrpl.resource
 xrpld.overlay > xrpl.server
 xrpld.overlay > xrpl.shamap
-xrpld.overlay > xrpl.telemetry
 xrpld.overlay > xrpl.tx
 xrpld.peerfinder > xrpl.basics
 xrpld.peerfinder > xrpld.app
@@ -306,7 +287,6 @@ xrpld.perflog > xrpl.config
 xrpld.perflog > xrpl.core
 xrpld.perflog > xrpld.app
 xrpld.perflog > xrpld.rpc
-xrpld.perflog > xrpld.telemetry
 xrpld.perflog > xrpl.json
 xrpld.perflog > xrpl.nodestore
 xrpld.perflog > xrpl.protocol
@@ -323,21 +303,9 @@ xrpld.rpc > xrpl.rdb
 xrpld.rpc > xrpl.resource
 xrpld.rpc > xrpl.server
 xrpld.rpc > xrpl.shamap
-xrpld.rpc > xrpl.telemetry
 xrpld.rpc > xrpl.tx
 xrpld.shamap > xrpl.basics
 xrpld.shamap > xrpld.core
 xrpld.shamap > xrpl.nodestore
 xrpld.shamap > xrpl.protocol
 xrpld.shamap > xrpl.shamap
-xrpld.telemetry > xrpl.basics
-xrpld.telemetry > xrpl.consensus
-xrpld.telemetry > xrpl.core
-xrpld.telemetry > xrpld.core
-xrpld.telemetry > xrpl.json
-xrpld.telemetry > xrpl.ledger
-xrpld.telemetry > xrpl.nodestore
-xrpld.telemetry > xrpl.protocol
-xrpld.telemetry > xrpl.rdb
-xrpld.telemetry > xrpl.server
-xrpld.telemetry > xrpl.telemetry

.github/scripts/otel-naming/README.md

@@ -1,82 +0,0 @@
-# OTel naming-consistency check
-
-`check_otel_naming.py` enforces the OpenTelemetry span-attribute naming
-convention documented in
-[CONTRIBUTING.md](../../../CONTRIBUTING.md#telemetry-span-attribute-naming)
-across every layer of the telemetry pipeline. The `*SpanNames.h` constants are
-the single source of truth (L1); every other layer must agree with them.
-
-## Running locally
-
-```
-python .github/scripts/otel-naming/check_otel_naming.py
-```
-
-It takes no arguments, can be run from any directory inside the repo, and uses
-only the Python standard library (no `pip install`, matching the levelization
-check). A non-zero exit code means a violation was found; the output lists each
-violation as `RULE | location | token | expected`.
-
-## What it checks
-
-The valid key set is **derived dynamically from the OTel code** — there is no
-hardcoded allowlist:
-
-- **L1 keys** come from the `namespace attr { ... }` blocks of every
-  `*SpanNames.h`, resolving the `makeStr("x")` / `join(seg::a, seg::b)` DSL
-  (cross-file, so `join(seg::rpc, ...)` resolves `seg::rpc` from the base
-  `SpanNames.h`). Each constant is resolved against **its own** header, so two
-  headers that define a same-named constant (e.g. a base `attr::ledgerHash` and
-  a domain `attr::ledgerHash`) each contribute their real wire key — a later
-  header cannot clobber an earlier one's value in a flat table.
-- **Legitimate dotted keys** = ONLY the keys the code actually sets as resource
-  attributes, i.e. the entries inside `Telemetry.cpp`'s `Resource::Create({...})`
-  call: the `semconv::service::*` keys (`service.*`) plus any `attr::<name>`
-  constants passed there (`xrpl.network.*`). A dotted key that is _declared_ in a
-  header but never set as a resource attr is a span attribute in resource
-  clothing — a Rule-A violation, even if it lives in the base `SpanNames.h`.
-- **L1-metrics** — instrument names, label keys and bounded label values come
-  from the `namespace metric` / `namespace label` / `namespace lval` blocks of
-  every `*MetricNames.h`, read as `inline constexpr char NAME[] = "wire";`.
-  These headers deliberately do **not** use the `makeStr`/`StaticStr` DSL the
-  span headers use: the OTel C++ API takes `nostd::string_view`, which
-  constructs from `char const*` but has no constructor from
-  `std::string_view`, so a `StaticStr` will not compile in an instrument-name
-  or label-key position.
-
-### Rules (each fails the build, when its inputs are present)
-
-| Rule | Check                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| A    | No stray dotted span-attribute key (only the derived resource keys may be dotted).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| G    | Attribute keys are `lower_snake_case` (`^[a-z][a-z0-9_]*$` per dot-segment) — no camelCase, UPPERCASE, or spaces.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| F    | No string literals as attribute keys or span-name arguments in `setAttribute`/`addEvent`/`span`/`rootSpan`/`childSpan` (`rootSpan` shares `span`'s `(cat, prefix, name)` signature). Attribute _values_ are exempt (runtime data); `*SpanNames.h` definitions and test files are exempt.                                                                                                                                                                                                                                                                                                   |
-| B    | Every collector `spanmetrics.dimensions` name exists in the L1 key set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| C    | Every Tempo span-filter tag exists in the L1 key set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| D    | Every dashboard label resolves to an L1 span attribute, a native-metric label (L6, emitted by MetricsRegistry), or a Prometheus/Grafana builtin. TraceQL scope prefixes (`span.`/`resource.`/…) are stripped before the L1 lookup.                                                                                                                                                                                                                                                                                                                                                         |
-| E    | No dotted `xrpl.<domain>.<field>` attribute key in the runbook (only the L1 resource attrs `xrpl.network.*` may be dotted). Span names, filenames, OTel-standard keys, and metric labels are not flagged.                                                                                                                                                                                                                                                                                                                                                                                  |
-| I    | No string literals as **metric** instrument names or label keys — the mirror of Rule F. Applies to the name passed to an `XRPL_METRIC_*` macro or a `meter->Create*` factory and to the label _keys_ in its label set. Label _values_, descriptions, `*MetricNames.h`, `MetricMacros.h` and test files are exempt. Scoped by metric **family** (first underscore segment): declaring a constant opts that family in, so the metric surface can be converted subsystem by subsystem. Unconverted families warn as Rule L.                                                                   |
-| J    | Metric instrument names follow the suffix conventions: `lower_snake_case`, no `xrpld_`/`xrpl_` prefix (the exporter adds it), a counter ends `_total`, a histogram ends `_us`/`_ms`/`_seconds`, a gauge does not end `_total`. The instrument **kind** is read from the emit site, never guessed from words in the name — so a multi-series gauge carrying units in its label values (e.g. `nodestore_state` observing `write_mean_us`) is not a violation. A name created through two different factories is itself reported as a kind conflict, since no suffix can be correct for both. |
-| K    | Every metric named in `docker/telemetry/workload/expected_metrics.json` resolves to a declared constant, so a rename in code cannot leave the workload validator asserting a name nothing emits. PromQL selectors (`m{label="v"}`) and exporter-appended histogram suffixes (`_bucket`/`_count`/`_sum`) are normalized away first; groups fed by another emit path (`statsd_gauges`, `statsd_counters`, `spanmetrics`) are out of scope by design.                                                                                                                                         |
-
-Rule F runs **unconditionally** (it is a purely syntactic check on the
-call-sites and needs no `*SpanNames.h`), so a code path that calls
-`SpanGuard::span`/`setAttribute` directly without ever defining a header is
-still caught.
-
-### Warnings (printed, never fail the build)
-
-| Rule | Check                                                                                                                                                                                                                                                                                                                                                                                      |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| H    | A namespace-qualified constant (e.g. `foo::bar::myKey`) used at a telemetry call-site is not defined in any `*SpanNames.h`. The constant should live in the proper header; defining it in-place bypasses rules A/G/F. Warns rather than fails — the argument may be a legitimately dynamic value, and the header may live on a later branch. Bare locals and `std::` names are not warned. |
-| L    | A literal metric name in a family that has no `*MetricNames.h` constants yet. Rule I's ratchet defers these instead of failing the build on the whole pre-existing metric surface at once; the warning keeps the outstanding conversion work visible rather than silently accepted.                                                                                                        |
-
-## Presence-gated
-
-Every rule runs **only when the source files it needs are present** in the tree
-and is otherwise skipped (printed as `SKIP: <rule> — <reason>`), never failed.
-This keeps the check correct no matter how telemetry work is split across PRs —
-a stacked chain, one large PR, or independent per-stage PRs where (for example)
-the collector config lands before the dashboards. The collector/Tempo/dashboard/
-runbook layers are introduced in later phases; on a branch without them, only
-the L1-intrinsic rules (A, G, F) run.

.github/scripts/rename/binary.sh

@@ -49,7 +49,7 @@ ${SED_COMMAND} -i -E 's@ripple/xrpld@XRPLF/rippled@g' BUILD.md
 ${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' BUILD.md
 ${SED_COMMAND} -i -E 's@xrpld \(`xrpld`\)@xrpld@g' BUILD.md
 ${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' CONTRIBUTING.md
-${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' docs/install.md
+${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' docs/build/install.md
 
 popd
 echo "Processing complete."

.github/scripts/rename/docs.sh

@@ -77,8 +77,8 @@ ${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/install.md
-${SED_COMMAND} -i 's@github.com/XRPLF/xrpld@github.com/XRPLF/rippled@g' docs/install.md
+${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

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

@@ -7,13 +7,7 @@ from pathlib import Path
 
 THIS_DIR = Path(__file__).parent.resolve()
 
-_BASE_CMAKE_ARGS = [
-    "-Dtests=ON",
-    "-Dwerr=ON",
-    "-Dxrpld=ON",
-    "-Dwextra=ON",
-    "-Drust=ON",
-]
+_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] = {
@@ -94,9 +88,6 @@ class PlatformConfig:
     build_only: bool = False  # if true, skip tests (e.g. macos/Windows Debug)
     benchmark: bool = False  # if true, smoke-run the benchmarks after testing
     extra_cmake_args: str = ""
-    # "" is the runner's system compiler, "nix" the flake's CI environment.
-    # macOS only: Linux always builds in a Nix image, Windows has no Nix.
-    toolchain: str = ""
 
     def __post_init__(self) -> None:
         if isinstance(self.build_type, str):
@@ -146,7 +137,6 @@ class MatrixEntry:
     sanitizers: str
     image: str = ""  # container image; empty for macOS/Windows (runs natively)
     compiler: str = ""  # compiler name ("gcc" or "clang"); empty for macOS/Windows
-    toolchain: str = ""  # "nix" for the flake's CI environment; see PlatformConfig
 
 
 @dataclasses.dataclass
@@ -225,7 +215,7 @@ def expand_linux_matrix(linux: LinuxFile, minimal: bool) -> list[MatrixEntry]:
 def expand_linux_packaging(linux: LinuxFile) -> list[PackagingEntry]:
     """Generate the packaging matrix from a LinuxFile's package_configs section.
 
-    Packaging uses vanilla distro images (debian:bookworm, almalinux:9) instead of
+    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'.
@@ -263,12 +253,9 @@ def expand_platform_matrix(pf: PlatformFile, minimal: bool) -> list[MatrixEntry]
         if minimal and not cfg.minimal:
             continue
         for build_type in cfg.build_type:
-            name = f"{platform_name}-{arch}-{build_type.lower()}"
-            if cfg.toolchain:
-                name += f"-{cfg.toolchain}"
             entries.append(
                 MatrixEntry(
-                    config_name=name,
+                    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,
@@ -276,7 +263,6 @@ def expand_platform_matrix(pf: PlatformFile, minimal: bool) -> list[MatrixEntry]
                     build_type=build_type,
                     architecture=Architecture(platform=pf.platform, runner=pf.runner),
                     sanitizers="",
-                    toolchain=cfg.toolchain,
                 )
             )
     return entries

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

@@ -1,5 +1,5 @@
 {
-  "image_tag": "sha-a0074f8",
+  "image_tag": "sha-fecfc0c",
   "configs": {
     "ubuntu": [
       {
@@ -92,7 +92,7 @@
         "build_type": ["Release"],
         "arch": ["amd64"],
         "minimal": false,
-        "image": "ghcr.io/xrplf/xrpld/packaging-debian:sha-a6983f8"
+        "image": "ghcr.io/xrplf/xrpld/packaging-debian:sha-577d745"
       }
     ],
 
@@ -102,7 +102,7 @@
         "build_type": ["Release"],
         "arch": ["amd64"],
         "minimal": false,
-        "image": "ghcr.io/xrplf/xrpld/packaging-rhel:sha-a6983f8"
+        "image": "ghcr.io/xrplf/xrpld/packaging-rhel:sha-577d745"
       }
     ]
   }

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

@@ -12,19 +12,6 @@
       "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
       "build_only": true,
       "minimal": false
-    },
-    {
-      "build_type": "Release",
-      "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
-      "toolchain": "nix",
-      "minimal": false
-    },
-    {
-      "build_type": "Debug",
-      "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
-      "toolchain": "nix",
-      "build_only": true,
-      "minimal": false
     }
   ]
 }

.github/scripts/telemetry/check_bucket_parity.py

@@ -1,128 +0,0 @@
-#!/usr/bin/env python3
-"""Assert the C++ millisecond ladder agrees with the collector's spanmetrics ladder.
-
-The two are specified to match so a span-derived latency panel and a native
-histogram panel can be read on the same scale. They *were* identical when first
-shipped. Then the collector ladder alone was extended -- sub-millisecond edges
-below 1ms and second-scale edges up to 30s -- and nothing checked the other
-side, so the C++ ladder stayed capped at 5s. Every quantile above 5s then read
-back as a flat 5000, because Prometheus returns the second-highest edge for a
-quantile landing in the `+Inf` bucket. That looks like a measurement rather
-than an error, which is why it survived for eleven phases.
-
-The rule is containment, not equality:
-
-  * every representable collector edge MUST appear in the C++ ladder, so the
-    shared range reads identically;
-  * the C++ ladder MAY carry extra edges ABOVE the collector's highest edge,
-    because jobs outlive spans -- the updatepaths job type was measured
-    averaging ~60s, which no span approaches. Demanding equality would force a
-    ceiling that censors it, reintroducing the bug this guards against;
-  * collector edges below 1ms are expected to be ABSENT rather than missing:
-    beast::insight::Event rounds every duration up to a whole millisecond
-    before it reaches the histogram, so those edges could never collect a
-    sample.
-
-Exit 0 when the ladders agree, 1 with a diff when they do not.
-"""
-
-import re
-import sys
-from pathlib import Path
-
-HEADER = Path("include/xrpl/telemetry/HistogramBuckets.h")
-COLLECTOR = Path("docker/telemetry/otel-collector-config.yaml")
-
-# beast::insight::Event applies ceil<milliseconds>, so anything below 1ms
-# collapses onto the 1ms edge.
-REPRESENTABLE_FLOOR_MS = 1.0
-
-UNIT_TO_MS = {"ms": 1.0, "s": 1000.0}
-
-
-def collector_edges_ms():
-    """Parse the spanmetrics bucket list, normalising each edge to milliseconds."""
-    text = COLLECTOR.read_text()
-    match = re.search(r"buckets:\s*\[(.*?)\]", text, re.S)
-    if not match:
-        sys.exit(f"{COLLECTOR}: no 'buckets:' list found")
-
-    edges = []
-    for raw in match.group(1).split(","):
-        token = raw.strip()
-        if not token:
-            continue
-        parsed = re.fullmatch(r"([0-9.]+)(ms|s)", token)
-        if not parsed:
-            sys.exit(f"{COLLECTOR}: cannot parse bucket edge {token!r}")
-        edges.append(float(parsed.group(1)) * UNIT_TO_MS[parsed.group(2)])
-    return edges
-
-
-def cpp_edges_ms():
-    """Parse kMillisecondBuckets out of the header that owns every ladder."""
-    text = HEADER.read_text()
-    match = re.search(r"kMillisecondBuckets\{(.*?)\};", text, re.S)
-    if not match:
-        sys.exit(f"{HEADER}: kMillisecondBuckets not found")
-    return [
-        float(token.strip().replace("'", ""))
-        for token in match.group(1).split(",")
-        if token.strip()
-    ]
-
-
-def main():
-    collector = collector_edges_ms()
-    cpp = cpp_edges_ms()
-    required = [edge for edge in collector if edge >= REPRESENTABLE_FLOOR_MS]
-    if not required:
-        sys.exit(f"{COLLECTOR}: no edges at or above {REPRESENTABLE_FLOOR_MS} ms")
-    collector_top = max(required)
-
-    missing = [edge for edge in required if edge not in cpp]
-    # An extra C++ edge inside the collector's range means the two scales
-    # disagree where they overlap. Above the collector's top it is a deliberate
-    # extension.
-    inside_range = [e for e in cpp if e not in required and e < collector_top]
-
-    if not missing and not inside_range:
-        extensions = [e for e in cpp if e > collector_top]
-        summary = f"OK: all {len(required)} representable collector edges present"
-        if extensions:
-            pretty = ", ".join(f"{e:g}" for e in extensions)
-            summary += (
-                f"; {len(extensions)} extension edge(s) above "
-                f"{collector_top:g} ms: [{pretty}]"
-            )
-        print(summary)
-        return 0
-
-    print("Bucket ladder parity violated.", file=sys.stderr)
-    print(
-        f"  collector (>= {REPRESENTABLE_FLOOR_MS:g} ms): "
-        f"{[f'{e:g}' for e in required]}",
-        file=sys.stderr,
-    )
-    print(
-        f"  HistogramBuckets.h            : {[f'{e:g}' for e in cpp]}", file=sys.stderr
-    )
-    for edge in missing:
-        print(f"  MISSING from the C++ ladder: {edge:g} ms", file=sys.stderr)
-    for edge in inside_range:
-        print(
-            f"  C++ edge {edge:g} ms lies inside the collector's range but is not "
-            "a collector edge -- add it to the collector or drop it here",
-            file=sys.stderr,
-        )
-    print(
-        "\nThe two ladders must agree over their shared range. Extra C++ edges are\n"
-        "permitted only ABOVE the collector's highest edge. Change both sides, or\n"
-        "change the spec in OpenTelemetryPlan/Phase7_taskList.md.",
-        file=sys.stderr,
-    )
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

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

@@ -36,9 +36,8 @@ jobs:
         distro:
           - name: debian
             base_image: debian:bookworm
-          # AlmaLinux rather than UBI9, which does not ship rpm-sign.
           - name: rhel
-            base_image: almalinux:9
+            base_image: registry.access.redhat.com/ubi9/ubi:latest
     uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@9e7e4e80af9e684c116b38369add8eea64451f32
     with:
       image_name: xrpld/packaging-${{ matrix.distro.name }}

.github/workflows/cargo-audit.yml

@@ -1,3 +1,8 @@
+# This workflow audits the Rust dependencies in crates/ for known security
+# advisories using cargo-audit. It runs on a weekly schedule, whenever the
+# dependency graph changes (Cargo.lock / Cargo.toml), and on demand. On a
+# scheduled run, a failure opens a tracking issue (matching the clang-tidy
+# workflow's behavior); on push/PR it simply fails the check.
 name: Cargo audit
 
 on:
@@ -7,7 +12,7 @@ on:
   push:
     branches:
       - "develop"
-      - "release/*"
+      - "release*"
     paths:
       - "crates/**/Cargo.toml"
       - "crates/Cargo.lock"
@@ -34,14 +39,14 @@ permissions:
 jobs:
   audit:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-a0074f8
+    container: ghcr.io/xrplf/xrpld/nix-debian:sha-2e25435
     permissions:
       contents: read
       # Needed to open an issue on scheduled failures.
       issues: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Run cargo audit
         id: audit
@@ -76,5 +81,4 @@ jobs:
         if: ${{ steps.audit.outcome != 'success' }}
         run: |
           echo "cargo audit found advisories!"
-          cat /tmp/cargo-audit.txt
           exit 1

.github/workflows/check-tools.yml

@@ -79,7 +79,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@51af40f99ea91a08c3528ddf16d98132dcc7e63c
+        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
         with:
           enable_ccache: false
 

.github/workflows/on-pr.yml

@@ -70,29 +70,15 @@ jobs:
           files: |
             # These paths are unique to `on-pr.yml`.
             .github/scripts/levelization/**
-            .github/scripts/otel-naming/**
             .github/scripts/rename/**
-            .github/scripts/telemetry/**
             .github/workflows/reusable-check-levelization.yml
-            .github/workflows/reusable-check-otel-naming.yml
             .github/workflows/reusable-check-rename.yml
             .github/workflows/on-pr.yml
 
-            # The non-code layers the OTel naming check validates: the docs that
-            # publish attribute tables (Rule E) and the telemetry stack config —
-            # collector, Tempo, dashboards (Rules B, C, D). Without these paths a
-            # docs-only or dashboard-only pull request sets `go=false`, so the
-            # very layers those rules exist to police would never be checked.
-            # As with `README.md` below, matching one of these also switches on
-            # the rest of the workflow; there is a single `go` gate.
-            docs/**
-            docker/telemetry/**
-
             # Keep the paths below in sync with those in `on-trigger.yml`.
             .github/actions/build-deps/**
-            .github/actions/release-info/**
+            .github/actions/generate-version/**
             .github/actions/setup-conan/**
-            .github/actions/setup-nix-env/**
             .github/scripts/strategy-matrix/**
             .github/workflows/reusable-build-test-config.yml
             .github/workflows/reusable-build-test.yml
@@ -105,7 +91,6 @@ jobs:
             .github/workflows/reusable-upload-recipe.yml
             .clang-tidy
             .codecov.yml
-            bin/check-nix-store-refs.sh
             bin/check-tools.sh
             bin/default-loader-path.sh
             cfg/**
@@ -119,9 +104,6 @@ jobs:
             CMakeLists.txt
             conanfile.py
             conan.lock
-            flake.lock
-            flake.nix
-            nix/**
             LICENSE.md
             package/**
             README.md
@@ -157,11 +139,6 @@ jobs:
     if: ${{ needs.should-run.outputs.go == 'true' }}
     uses: ./.github/workflows/reusable-check-levelization.yml
 
-  check-otel-naming:
-    needs: should-run
-    if: ${{ needs.should-run.outputs.go == 'true' }}
-    uses: ./.github/workflows/reusable-check-otel-naming.yml
-
   check-rename:
     needs: should-run
     if: ${{ needs.should-run.outputs.go == 'true' }}
@@ -240,7 +217,6 @@ jobs:
     needs:
       - check-autogen
       - check-levelization
-      - check-otel-naming
       - check-rename
       - clang-tidy
       - build-test

.github/workflows/on-tag.yml

@@ -1,9 +1,5 @@
-# When a versioned tag is pushed, this workflow:
-#
-#   - uploads the libxrpl recipe to the Conan remote
-#   - builds and tests the release binaries
-#   - builds the DEB and RPM packages
-#   - publishes those packages to the XRPLF package repositories
+# This workflow uploads the libxrpl recipe to the Conan remote and builds
+# release packages when a versioned tag is pushed.
 name: Tag
 
 on:
@@ -28,7 +24,7 @@ jobs:
       remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
 
   build-test:
-    if: ${{ github.repository_owner == 'XRPLF' }}
+    if: ${{ github.repository == 'XRPLF/rippled' }}
     uses: ./.github/workflows/reusable-build-test.yml
     strategy:
       fail-fast: true
@@ -41,12 +37,6 @@ jobs:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   package:
-    if: ${{ github.repository_owner == 'XRPLF' }}
+    if: ${{ github.repository == 'XRPLF/rippled' }}
     needs: build-test
     uses: ./.github/workflows/reusable-package.yml
-    with:
-      publish: true
-    secrets:
-      remote_username: ${{ secrets.NEXUS_REMOTE_USERNAME }}
-      remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
-      signing_key: ${{ secrets.NEXUS_PACKAGES_PRIVATE_KEY }}

.github/workflows/on-trigger.yml

@@ -15,9 +15,8 @@ on:
 
       # Keep the paths below in sync with those in `on-pr.yml`.
       - ".github/actions/build-deps/**"
-      - ".github/actions/release-info/**"
+      - ".github/actions/generate-version/**"
       - ".github/actions/setup-conan/**"
-      - ".github/actions/setup-nix-env/**"
       - ".github/scripts/strategy-matrix/**"
       - ".github/workflows/reusable-build-test-config.yml"
       - ".github/workflows/reusable-build-test.yml"
@@ -30,7 +29,6 @@ on:
       - ".github/workflows/reusable-upload-recipe.yml"
       - ".clang-tidy"
       - ".codecov.yml"
-      - "bin/check-nix-store-refs.sh"
       - "bin/check-tools.sh"
       - "bin/default-loader-path.sh"
       - "cfg/**"
@@ -44,9 +42,6 @@ on:
       - "CMakeLists.txt"
       - "conanfile.py"
       - "conan.lock"
-      - "flake.lock"
-      - "flake.nix"
-      - "nix/**"
       - "LICENSE.md"
       - "package/**"
       - "README.md"
@@ -120,11 +115,3 @@ jobs:
   package:
     needs: build-test
     uses: ./.github/workflows/reusable-package.yml
-    with:
-      # Packages are built on every trigger; only develop pushes in XRPLF/rippled
-      # publish them, matching upload-recipe above.
-      publish: ${{ github.repository == 'XRPLF/rippled' && github.event_name == 'push' && github.ref == 'refs/heads/develop' }}
-    secrets:
-      remote_username: ${{ secrets.NEXUS_REMOTE_USERNAME }}
-      remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
-      signing_key: ${{ secrets.NEXUS_PACKAGES_PRIVATE_KEY }}

.github/workflows/publish-docs.yml

@@ -41,13 +41,13 @@ env:
 jobs:
   build:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-a0074f8
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-fecfc0c
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@51af40f99ea91a08c3528ddf16d98132dcc7e63c
+        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
         with:
           enable_ccache: false
 

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

@@ -69,12 +69,6 @@ on:
         type: string
         default: ""
 
-      toolchain:
-        description: 'Where the toolchain comes from ("nix" to build the flake CI environment on the runner, empty for the system one). macOS only: Linux always builds in a Nix image, and Nix has no Windows support.'
-        required: false
-        type: string
-        default: ""
-
     secrets:
       CODECOV_TOKEN:
         description: "The Codecov token to use for uploading coverage reports."
@@ -117,9 +111,6 @@ jobs:
       VOIDSTAR_ENABLED: ${{ contains(inputs.cmake_args, '-Dvoidstar=ON') }}
       VALIDATOR_KEYS_ENABLED: ${{ contains(inputs.cmake_args, '-Dvalidator_keys=ON') }}
       SANITIZERS_ENABLED: ${{ inputs.sanitizers != '' }}
-      # The binaries reusable-package.yml consumes. A private repository skips
-      # them except on a tag push, which is what produces its release packages.
-      PACKAGING_ARTIFACTS_ENABLED: ${{ github.event.repository.visibility == 'public' || startsWith(github.ref, 'refs/tags/') }}
     steps:
       - name: Cleanup workspace (macOS and Windows)
         if: ${{ runner.os == 'macOS' || runner.os == 'Windows' }}
@@ -129,15 +120,10 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@51af40f99ea91a08c3528ddf16d98132dcc7e63c
+        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
         with:
           enable_ccache: ${{ inputs.ccache_enabled }}
 
-      # Before any step that uses a build tool, composite actions included.
-      - name: Setup Nix environment
-        if: ${{ inputs.toolchain == 'nix' }}
-        uses: ./.github/actions/setup-nix-env
-
       - name: Set ccache log file
         if: ${{ inputs.ccache_enabled && runner.debug == '1' }}
         run: echo "CCACHE_LOGFILE=${{ runner.temp }}/ccache.log" >>"${GITHUB_ENV}"
@@ -162,22 +148,7 @@ jobs:
         with:
           compiler: ${{ inputs.compiler }}
 
-      - name: Use cargo artifacts cache
-        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
-        with:
-          cache-directories: ${{ env.BUILD_DIR }}/corrosion
-          key: ${{ inputs.config_name }}
-          save-if: ${{ github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/heads/release') }}
-          # two workspaces here because build artifacts are located in 2 places:
-          # - crates/target when cargo is called directly
-          # - build/cargo when cargo is called by cmake
-          workspaces: |
-            crates
-            crates -> ${{ runner.os == 'Windows' && format('../{0}/x64/{1}/cargo', env.BUILD_DIR, inputs.build_type) || format('../{0}/cargo', env.BUILD_DIR) }}
-
-      # `setup-nix-env` already did this for the Nix toolchain.
       - name: Setup Conan
-        if: ${{ inputs.toolchain != 'nix' }}
         env:
           SANITIZERS: ${{ inputs.sanitizers }}
         uses: ./.github/actions/setup-conan
@@ -241,24 +212,6 @@ jobs:
               --target "${CMAKE_TARGET}" \
               2>&1 | tee "${GITHUB_WORKSPACE}/build.log"
 
-      # Nothing may reference the store, so whole trees are checked - the Conan
-      # cache included, since what it holds is what gets uploaded and reused.
-      - name: Check the build output for Nix store references (Nix toolchain)
-        if: ${{ inputs.toolchain == 'nix' }}
-        run: ./bin/check-nix-store-refs.sh "${BUILD_DIR}"
-
-      - name: Check the Conan cache for Nix store references (Nix toolchain)
-        if: ${{ inputs.toolchain == 'nix' }}
-        run: ./bin/check-nix-store-refs.sh "${CONAN_HOME}"
-
-      # Only what PatchNixBinary.cmake retargets: the toolchain in the Linux
-      # images always references the store. Same condition it uses.
-      - name: Check for Nix store references (Linux)
-        if: ${{ runner.os == 'Linux' && env.SANITIZERS_ENABLED == 'false' }}
-        run: |
-          ./bin/check-nix-store-refs.sh "${BUILD_DIR}/xrpld"
-          ./bin/check-nix-store-refs.sh "${BUILD_DIR}/xrpl_tests"
-
       - name: Show ccache statistics
         if: ${{ inputs.ccache_enabled }}
         run: |
@@ -269,7 +222,7 @@ jobs:
           fi
 
       - name: Upload the binary (Linux)
-        if: ${{ env.PACKAGING_ARTIFACTS_ENABLED == 'true' && runner.os == 'Linux' }}
+        if: ${{ github.event.repository.visibility == 'public' && runner.os == 'Linux' }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: xrpld-${{ inputs.config_name }}
@@ -283,7 +236,7 @@ jobs:
         run: ./validator-keys --unittest
 
       - name: Upload the validator-keys binary
-        if: ${{ env.PACKAGING_ARTIFACTS_ENABLED == 'true' && env.VALIDATOR_KEYS_ENABLED == 'true' }}
+        if: ${{ github.event.repository.visibility == 'public' && env.VALIDATOR_KEYS_ENABLED == 'true' }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: validator-keys-${{ inputs.config_name }}
@@ -323,7 +276,7 @@ jobs:
         working-directory: ${{ env.BUILD_DIR }}
         run: |
           ldd ./xrpld
-          if [ "$(ldd ./xrpld | grep -E '(libstdc\+\+|libgcc)' | wc -l)" -eq 0 ]; then
+          if [ "$(ldd ./xrpld | grep -E '(libstdc\+\+)' | wc -l)" -eq 0 ]; then
               echo 'The binary is statically linked.'
           else
               echo 'The binary is dynamically linked.'
@@ -336,6 +289,14 @@ jobs:
         run: |
           ./xrpld --version | grep libvoidstar
 
+      - name: Run Rust tests
+        if: ${{ !inputs.build_only }}
+        working-directory: crates
+        # `xrpl-wasm-vm-ffi` is left out on Windows: its tests link as an executable, and
+        # MSVC - unlike the Unix linkers - will not dead-strip the never-called cxx wrappers
+        # whose C++ shims only the CMake build defines. The other runners cover these tests.
+        run: cargo nextest run --workspace --all-features --locked --no-tests=warn ${{ runner.os == 'Windows' && '--exclude xrpl-wasm-vm-ffi' || '' }}
+
       - 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 }}
@@ -370,11 +331,6 @@ jobs:
 
           LD_PRELOAD="$PRELOAD" ./xrpld --unittest --unittest-jobs "${BUILD_NPROC}" 2>&1 | tee "${GITHUB_WORKSPACE}/unittest.log"
 
-      - name: Run Rust tests
-        if: ${{ !inputs.build_only }}
-        working-directory: crates
-        run: cargo nextest run --workspace --all-features --locked --no-tests=warn
-
       # Smoke-run every benchmark module with a single repetition to confirm the
       # benchmarks still build and execute. This is a correctness check, not a
       # performance measurement, so there is nothing to gain from repeating it

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

@@ -51,6 +51,5 @@ jobs:
       config_name: ${{ matrix.config_name }}
       sanitizers: ${{ matrix.sanitizers }}
       compiler: ${{ matrix.compiler || '' }}
-      toolchain: ${{ matrix.toolchain || '' }}
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/reusable-check-otel-naming.yml

@@ -1,43 +0,0 @@
-# This workflow checks that OpenTelemetry span-attribute names stay consistent
-# across the code (*SpanNames.h), collector, Tempo, dashboards, and docs.
-# See .github/scripts/otel-naming/check_otel_naming.py and the
-# "Telemetry span attribute naming" section in CONTRIBUTING.md.
-name: Check OTel naming
-
-# This workflow can only be triggered by other workflows.
-on: workflow_call
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}-otel-naming
-  cancel-in-progress: true
-
-defaults:
-  run:
-    shell: bash
-
-jobs:
-  otel-naming:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - name: Test the OTel naming checker
-        # The checker's own unit tests, run before the check itself so a broken
-        # rule is reported as a broken rule rather than as a naming violation
-        # (or, worse, as a rule that silently stops flagging anything).
-        # stdlib `unittest` only: the repo installs no third-party test runner
-        # for CI, and the checker itself is deliberately dependency-free.
-        run: python -m unittest discover -s .github/scripts/otel-naming -p 'test_*.py' --verbose
-      - name: Check OTel naming
-        # The script is stdlib-only and reads only files already in the tree;
-        # it enforces each rule only when the layer it needs is present, so it
-        # works whether telemetry changes land in one PR or several.
-        run: python .github/scripts/otel-naming/check_otel_naming.py
-      - name: Check histogram bucket parity
-        # The C++ millisecond ladder and the collector's spanmetrics ladder are
-        # specified to agree over their shared range. They were identical when
-        # first shipped, then the collector side alone was extended and nothing
-        # noticed for eleven phases: native histograms stayed capped at 5s while
-        # spans reached 30s, so every quantile above 5s reported a flat 5000.
-        # Nothing but a check keeps two lists in step.
-        run: python .github/scripts/telemetry/check_bucket_parity.py

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

@@ -34,7 +34,7 @@ jobs:
     needs: [determine-files]
     if: ${{ needs.determine-files.outputs.cpp_changed_files != '' || needs.determine-files.outputs.need_full_run == 'true' }}
     runs-on: ["self-hosted", "Linux", "X64", "heavy"]
-    container: "ghcr.io/xrplf/xrpld/nix-debian:sha-a0074f8"
+    container: "ghcr.io/xrplf/xrpld/nix-debian:sha-fecfc0c"
     permissions:
       contents: read
       issues: write
@@ -43,7 +43,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@51af40f99ea91a08c3528ddf16d98132dcc7e63c
+        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
         with:
           enable_ccache: false
 
@@ -59,13 +59,6 @@ jobs:
         with:
           compiler: ${{ env.COMPILER }}
 
-      - name: Use cargo artifacts cache
-        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
-        with:
-          cache-directories: ${{ env.BUILD_DIR }}/corrosion
-          save-if: ${{ github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/heads/release') }}
-          workspaces: crates -> ../${{ env.BUILD_DIR }}/cargo
-
       - name: Setup Conan
         uses: ./.github/actions/setup-conan
 
@@ -87,13 +80,19 @@ jobs:
               -Dwerr=ON \
               -Dxrpld=ON \
               -Dverify_headers=ON \
-              -Drust=ON \
               ..
 
-      - name: Build clang-tidy prerequisites
+      # clang-tidy needs headers generated from proto files
+      - name: Build libxrpl.libpb
         working-directory: ${{ env.BUILD_DIR }}
         run: |
-          ninja -j ${{ steps.nproc.outputs.nproc }} tidy_prerequisites
+          ninja -j ${{ steps.nproc.outputs.nproc }} xrpl.libpb
+
+      # clang-tidy needs cxxbridge headers generated from Rust crates
+      - name: Build xrpl_crates
+        working-directory: ${{ env.BUILD_DIR }}
+        run: |
+          ninja -j ${{ steps.nproc.outputs.nproc }} xrpl_crates
 
       - name: Run clang tidy
         id: run_clang_tidy

.github/workflows/reusable-package.yml

@@ -1,37 +1,17 @@
-# Build Linux packages from the pre-built xrpld and validator-keys artifacts:
-#
-#   - one job per distro, taken from "package_configs" in linux.json
-#   - each job runs in that distro's container, which is what decides DEB or RPM
-#   - with 'publish: true' a job also uploads what it built
-#     (see package/publish_pkg.sh)
-#
-# Only linux/amd64 is supported; the runner is hardcoded in the job below.
+# Build Linux packages (DEB and RPM) from pre-built binary artifacts (xrpld and
+# validator-keys). 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:
-      publish:
-        description: "Whether to publish the packages after building them."
-        required: false
-        type: boolean
-        default: false
-      nexus_url:
-        description: "The base URL of the Nexus instance hosting the deb and rpm repositories."
+      pkg_release:
+        description: "Package release number. Increment when repackaging the same executable."
         required: false
         type: string
-        default: https://packages.xrplf.org
-
-    secrets:
-      remote_username:
-        description: "The username of a Nexus account with write access to the repositories."
-        required: false
-      remote_password:
-        description: "The password or token for that Nexus account."
-        required: false
-      signing_key:
-        description: "Armoured PGP private key used to sign the RPMs. Required when publishing."
-        required: false
+        default: "1"
 
 defaults:
   run:
@@ -61,7 +41,7 @@ jobs:
 
   package:
     needs: [generate-matrix]
-    if: ${{ github.event.repository.visibility == 'public' || startsWith(github.ref, 'refs/tags/') }}
+    if: ${{ github.event.repository.visibility == 'public' }}
     strategy:
       fail-fast: false
       matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
@@ -91,24 +71,11 @@ jobs:
       - name: Make binaries executable
         run: chmod +x "${BUILD_DIR}/xrpld" "${BUILD_DIR}/validator-keys"
 
-      - name: Determine release info
-        id: release_info
-        uses: ./.github/actions/release-info
-
       - name: Build package
         env:
-          PKG_RELEASE: ${{ steps.release_info.outputs.pkg_release }}
-          PKG_CHANNEL: ${{ steps.release_info.outputs.channel }}
+          PKG_RELEASE: ${{ inputs.pkg_release }}
         run: ./package/build_pkg.sh
 
-      # Before the upload, so the artifact and the published package are the
-      # same bytes. DEBs are not signed, so the key is never set on that job.
-      - name: Sign RPM
-        if: ${{ inputs.publish && matrix.distro == 'rhel' }}
-        env:
-          PKG_SIGNING_KEY: ${{ secrets.signing_key }}
-        run: ./package/sign_rpm.sh "${BUILD_DIR}"
-
       - name: Upload package artifact
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
@@ -118,12 +85,3 @@ jobs:
             ${{ env.BUILD_DIR }}/debbuild/*.ddeb
             ${{ env.BUILD_DIR }}/rpmbuild/RPMS/**/*.rpm
           if-no-files-found: error
-
-      - name: Publish package
-        if: ${{ inputs.publish }}
-        env:
-          CHANNEL: ${{ steps.release_info.outputs.channel }}
-          NEXUS_URL: ${{ inputs.nexus_url }}
-          NEXUS_USERNAME: ${{ secrets.remote_username }}
-          NEXUS_PASSWORD: ${{ secrets.remote_password }}
-        run: ./package/publish_pkg.sh "${CHANNEL}" "${BUILD_DIR}"

.github/workflows/reusable-rust.yml

@@ -14,7 +14,7 @@ on:
     secrets:
       CODECOV_TOKEN:
         description: "The Codecov token to use for uploading coverage reports."
-        required: true
+        required: false
 
 defaults:
   run:
@@ -27,13 +27,13 @@ permissions:
 jobs:
   clippy:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-a0074f8
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-fecfc0c
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
-      - name: Use cargo artifacts cache
-        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+      - name: Cache cargo artifacts
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
         with:
           workspaces: crates
 
@@ -42,13 +42,13 @@ jobs:
 
   coverage:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-a0074f8
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-fecfc0c
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
-      - name: Use cargo artifacts cache
-        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+      - name: Cache cargo artifacts
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
         with:
           workspaces: crates
 
@@ -70,13 +70,13 @@ jobs:
 
   doc:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-a0074f8
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-fecfc0c
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
-      - name: Use cargo artifacts cache
-        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+      - name: Cache cargo artifacts
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
         with:
           workspaces: crates
 

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

@@ -40,7 +40,7 @@ defaults:
 jobs:
   upload:
     runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-a0074f8
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-fecfc0c
     env:
       REMOTE_NAME: ${{ inputs.remote_name }}
       CONAN_LOGIN_USERNAME_XRPLF: ${{ secrets.remote_username }}
@@ -49,9 +49,9 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - name: Determine release info
-        id: release_info
-        uses: ./.github/actions/release-info
+      - name: Generate build version number
+        id: version
+        uses: ./.github/actions/generate-version
 
       - name: Set up Conan
         uses: ./.github/actions/setup-conan
@@ -64,8 +64,8 @@ jobs:
 
       - name: Upload Conan recipe (version)
         run: |
-          conan export . --version=${{ steps.release_info.outputs.version }}
-          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/${{ steps.release_info.outputs.version }}
+          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.
@@ -92,4 +92,4 @@ jobs:
           conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/release
 
     outputs:
-      ref: xrpl/${{ steps.release_info.outputs.version }}
+      ref: xrpl/${{ steps.version.outputs.version }}

.github/workflows/telemetry-validation.yml

@@ -1,382 +0,0 @@
-# Telemetry Validation CI Workflow
-#
-# Builds rippled with telemetry enabled, runs the multi-node workload
-# harness, validates all telemetry data, and runs performance benchmarks.
-#
-# This is a separate workflow from the main CI. It runs:
-#   - On manual dispatch (workflow_dispatch)
-#   - On pushes to telemetry-related branches
-#
-# The workflow is intentionally heavyweight (builds rippled, starts Docker
-# services, runs a multi-node cluster) — it validates the full telemetry
-# stack end-to-end rather than individual unit tests.
-#
-# Architecture: three jobs to leverage cached dependencies:
-#   0. linux-image-tag — reads the CI image tag from the build matrix so this
-#      workflow cannot drift onto a different compiler than the main CI.
-#   1. build-xrpld — runs on a self-hosted runner inside the same container
-#      image the main CI uses. This ensures Conan packages are fetched from
-#      the XRPLF remote instead of built from source, and ccache hits the
-#      remote cache.
-#   2. validate-telemetry — runs on ubuntu-latest (which has Docker) to
-#      launch the telemetry stack (OTel collector, Prometheus, Tempo, etc.)
-#      and validate the full pipeline end-to-end.
-
-name: Telemetry Validation
-
-on:
-  workflow_dispatch:
-    # NOTE: rpc_rate / rpc_duration / tx_tps / tx_duration have NO effect.
-    # They are forwarded to run-full-validation.sh, which parses them into
-    # shell variables and never reads them again — load shape comes entirely
-    # from --profile and docker/telemetry/workload/workload-profiles.json.
-    # They are kept (and labelled) rather than removed so existing dispatch
-    # bookmarks and any saved input sets do not break. To change the load,
-    # edit or add a profile in workload-profiles.json.
-    inputs:
-      rpc_rate:
-        description: "UNUSED — has no effect. Load shape comes from the workload profile."
-        required: false
-        default: "50"
-      rpc_duration:
-        description: "UNUSED — has no effect. Load shape comes from the workload profile."
-        required: false
-        default: "120"
-      tx_tps:
-        description: "UNUSED — has no effect. Load shape comes from the workload profile."
-        required: false
-        default: "5"
-      tx_duration:
-        description: "UNUSED — has no effect. Load shape comes from the workload profile."
-        required: false
-        default: "120"
-      run_benchmark:
-        description: "Run performance benchmarks (the only input that changes behaviour)"
-        required: false
-        type: boolean
-        default: false
-
-  push:
-    branches:
-      - "pratik/otel-phase*"
-      - "feature/otel-*"
-      - "feature/telemetry-*"
-    # Keep these globs pointing at paths that actually exist. Two earlier
-    # entries (include/xrpl/basics/Telemetry*.h, src/xrpld/app/misc/Telemetry*)
-    # matched zero tracked files, so a pure C++ telemetry change never
-    # triggered this workflow on push — only edits under docker/telemetry/**
-    # or to this file did. The telemetry sources live in the three telemetry
-    # module directories below.
-    paths:
-      - ".github/workflows/telemetry-validation.yml"
-      - "docker/telemetry/**"
-      - "include/xrpl/telemetry/**"
-      - "src/libxrpl/telemetry/**"
-      - "src/libxrpl/beast/insight/**"
-      - "src/xrpld/telemetry/**"
-
-concurrency:
-  group: telemetry-validation-${{ github.ref }}
-  cancel-in-progress: true
-
-defaults:
-  run:
-    shell: bash
-
-env:
-  BUILD_DIR: build
-
-jobs:
-  # ── Job 0: Resolve the CI image tag ────────────────────────────────
-  # The tag is pinned once, alongside the build matrix, in linux.json. Reading
-  # it here rather than hardcoding a second copy means this workflow always
-  # builds in the same image (and therefore the same compiler) as the main CI.
-  # A hardcoded copy silently went stale and left this job on gcc 13 after the
-  # rest of CI moved to gcc 15, which broke the build on code the main CI
-  # compiled fine.
-  linux-image-tag:
-    runs-on: ubuntu-latest
-    outputs:
-      tag: ${{ steps.tag.outputs.tag }}
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Read nix image tag
-        id: tag
-        run: echo "tag=$(jq -r .image_tag .github/scripts/strategy-matrix/linux.json)" >>"${GITHUB_OUTPUT}"
-
-  # ── Job 1: Build xrpld in the same container the main CI uses ──────
-  # This ensures Conan binary packages are fetched from the XRPLF remote
-  # (matching package IDs) and ccache hits the remote compilation cache.
-  build-xrpld:
-    name: Build xrpld
-    needs: linux-image-tag
-    runs-on: [self-hosted, Linux, X64, heavy]
-    container: ghcr.io/xrplf/xrpld/nix-debian:${{ needs.linux-image-tag.outputs.tag }}
-    timeout-minutes: 60
-    env:
-      CCACHE_NAMESPACE: telemetry-validation
-      CCACHE_REMOTE_ONLY: true
-      CCACHE_REMOTE_STORAGE: http://cache.dev.ripplex.io:8080|layout=bazel
-      CCACHE_SLOPPINESS: include_file_ctime,include_file_mtime
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@c00c22ada3bd6bcda48fcb0d62fbbab49fec8a0f
-        with:
-          enable_ccache: ${{ github.repository_owner == 'XRPLF' }}
-
-      - name: Print build environment
-        uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574
-
-      - name: Get number of processors
-        uses: XRPLF/actions/get-nproc@cf0433aa74563aead044a1e395610c96d65a37cf
-        id: nproc
-        with:
-          subtract: 2
-
-      # The nix image ships several toolchains, so CC/CXX must be set
-      # explicitly for Conan to detect the intended one. gcc matches the
-      # debian gcc-release config the main CI builds.
-      - name: Set compiler environment
-        uses: ./.github/actions/set-compiler-env
-        with:
-          compiler: gcc
-
-      - 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: Release
-          log_verbosity: verbose
-
-      # telemetry is passed explicitly even though the CMake option and the
-      # Conan recipe both default it on. The whole point of this workflow is to
-      # exercise telemetry, so it should not silently depend on a default it
-      # does not control: if that default ever flips, every span and metric
-      # assertion would fail for a reason no log names. Stated here, a build
-      # without the dependency fails loudly instead, because CMakeLists.txt
-      # does find_package(opentelemetry-cpp CONFIG REQUIRED) under this option.
-      - name: Configure CMake
-        working-directory: ${{ env.BUILD_DIR }}
-        run: |
-          cmake \
-              -G Ninja \
-              -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
-              -DCMAKE_BUILD_TYPE=Release \
-              -Dtelemetry=ON \
-              ..
-
-      - name: Build xrpld
-        working-directory: ${{ env.BUILD_DIR }}
-        env:
-          BUILD_NPROC: ${{ steps.nproc.outputs.nproc }}
-        run: |
-          cmake \
-              --build . \
-              --config Release \
-              --parallel "${BUILD_NPROC}" \
-              --target xrpld
-
-      - name: Show ccache statistics
-        if: ${{ github.repository_owner == 'XRPLF' }}
-        run: ccache --show-stats -vv
-
-      - name: Upload xrpld binary
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: xrpld-telemetry
-          path: ${{ env.BUILD_DIR }}/xrpld
-          retention-days: 1
-          if-no-files-found: error
-
-  # ── Job 2: Run telemetry validation on ubuntu-latest (has Docker) ──
-  validate-telemetry:
-    name: Telemetry Stack Validation
-    needs: build-xrpld
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Install Python dependencies
-        run: pip3 install -r docker/telemetry/workload/requirements.txt
-
-      - name: Download xrpld binary
-        uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.2.1
-        with:
-          name: xrpld-telemetry
-          path: ${{ env.BUILD_DIR }}
-
-      - name: Make binaries and scripts executable
-        run: |
-          chmod +x ${{ env.BUILD_DIR }}/xrpld
-          chmod +x docker/telemetry/workload/*.sh
-
-      - name: Run full telemetry validation
-        id: validation
-        env:
-          RPC_RATE: ${{ github.event.inputs.rpc_rate || '50' }}
-          RPC_DURATION: ${{ github.event.inputs.rpc_duration || '120' }}
-          TX_TPS: ${{ github.event.inputs.tx_tps || '5' }}
-          TX_DURATION: ${{ github.event.inputs.tx_duration || '120' }}
-          RUN_BENCHMARK: ${{ github.event.inputs.run_benchmark }}
-        run: |
-          # The four rate/duration flags below are inert (see the
-          # workflow_dispatch inputs note): run-full-validation.sh parses them
-          # and never reads them. Load shape comes from the default
-          # --profile full-validation. They are still passed so the flags stay
-          # exercised if they are ever wired up.
-          ARGS="--xrpld ${{ env.BUILD_DIR }}/xrpld --skip-loki"
-          ARGS="$ARGS --rpc-rate $RPC_RATE"
-          ARGS="$ARGS --rpc-duration $RPC_DURATION"
-          ARGS="$ARGS --tx-tps $TX_TPS"
-          ARGS="$ARGS --tx-duration $TX_DURATION"
-          if [ "$RUN_BENCHMARK" = "true" ]; then
-              ARGS="$ARGS --with-benchmark"
-          fi
-          docker/telemetry/workload/run-full-validation.sh $ARGS
-        # continue-on-error allows subsequent steps (artifact upload,
-        # summary printing) to run even if validation fails. The final
-        # "Check validation result" step re-checks steps.validation.outcome
-        # (the pre-continue-on-error result) and fails the job properly.
-        continue-on-error: true
-
-      - name: Upload validation reports
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: telemetry-validation-reports
-          path: /tmp/xrpld-validation/reports/
-          retention-days: 30
-
-      # Keyed on the validation step's own outcome, not job status. The step
-      # above sets continue-on-error, so the job is not failing at this point
-      # and `if: failure()` never fires -- which silently skipped these logs on
-      # every failed run, and they are the only record of why a node did not
-      # reach consensus.
-      #
-      # stdout.log matters as much as debug.log: a node that dies before its
-      # log sink opens writes no debug.log at all, so stdout is the only place
-      # its reason survives. A run that timed out at 4/5 nodes was left
-      # undiagnosable because that file was not collected.
-      - name: Upload node logs
-        if: always() && steps.validation.outcome != 'success'
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: xrpld-node-logs
-          path: |
-            /tmp/xrpld-validation/node*/debug.log
-            /tmp/xrpld-validation/node*/stdout.log
-            /tmp/xrpld-validation/*.log
-          retention-days: 7
-          if-no-files-found: warn
-
-      - name: Print validation summary
-        if: always()
-        run: |
-          REPORT="/tmp/xrpld-validation/reports/validation-report.json"
-          if [ -f "$REPORT" ]; then
-              echo "## Telemetry Validation Results" >>"$GITHUB_STEP_SUMMARY"
-              echo "" >>"$GITHUB_STEP_SUMMARY"
-              TOTAL=$(jq '.summary.total' "$REPORT")
-              PASSED=$(jq '.summary.passed' "$REPORT")
-              FAILED=$(jq '.summary.failed' "$REPORT")
-              echo "| Metric | Value |" >>"$GITHUB_STEP_SUMMARY"
-              echo "|--------|-------|" >>"$GITHUB_STEP_SUMMARY"
-              echo "| Total Checks | $TOTAL |" >>"$GITHUB_STEP_SUMMARY"
-              echo "| Passed | $PASSED |" >>"$GITHUB_STEP_SUMMARY"
-              echo "| Failed | $FAILED |" >>"$GITHUB_STEP_SUMMARY"
-              echo "" >>"$GITHUB_STEP_SUMMARY"
-              if [ "$FAILED" -gt 0 ]; then
-                  echo "### Failed Checks" >>"$GITHUB_STEP_SUMMARY"
-                  echo "" >>"$GITHUB_STEP_SUMMARY"
-                  jq -r '.checks[] | select(.passed == false) | "- **\(.name)**: \(.message)"' "$REPORT" >>"$GITHUB_STEP_SUMMARY"
-              fi
-          fi
-
-      # Publishes captured OTel timings + regression report to the Step Summary.
-      # When the committed baseline is a placeholder, emits a fenced JSON block
-      # that can be copy-pasted directly into baselines/baseline-timings.json.
-      # When the baseline is populated, summarises the top regressions so the
-      # PR author sees the failure reason without downloading artifacts.
-      - name: Print regression summary
-        if: always()
-        run: |
-          set -euo pipefail
-          TIMINGS="/tmp/xrpld-validation/reports/timings.json"
-          REGRESSION="/tmp/xrpld-validation/reports/regression-report.json"
-          BASELINE="docker/telemetry/workload/baselines/baseline-timings.json"
-
-          if [ ! -f "$TIMINGS" ]; then
-              echo "## Regression Gate: no timings captured" >>"$GITHUB_STEP_SUMMARY"
-              echo "::warning::capture_timings.py did not produce timings.json — regression gate was not evaluated."
-              exit 0
-          fi
-
-          if [ ! -f "$BASELINE" ]; then
-              echo "## Regression Gate: baseline file missing" >>"$GITHUB_STEP_SUMMARY"
-              echo "::error::baselines/baseline-timings.json not found in checkout"
-              exit 1
-          fi
-
-          # NOTE: do NOT use `jq -e` here. With -e, jq exits non-zero when the
-          # filter's result is boolean false — which is the normal case for a
-          # populated (non-placeholder) baseline — and that would be
-          # misreported as a parse failure. Plain `jq -r` exits 0 on any valid
-          # JSON, so a real non-zero exit genuinely means malformed JSON.
-          IS_PLACEHOLDER=$(jq -r '.placeholder == true or (.metrics | length == 0)' "$BASELINE") || {
-              echo "::error::Failed to parse baseline JSON"
-              exit 1
-          }
-
-          echo "## OTel Timings Regression Gate" >>"$GITHUB_STEP_SUMMARY"
-          echo "" >>"$GITHUB_STEP_SUMMARY"
-
-          if [ "$IS_PLACEHOLDER" = "true" ]; then
-              echo "### Paste into \`baselines/baseline-timings.json\`" >>"$GITHUB_STEP_SUMMARY"
-              echo "" >>"$GITHUB_STEP_SUMMARY"
-              echo "The committed baseline is a placeholder. Open a PR replacing" \
-                  "its contents with the JSON block below to activate the" \
-                  "regression gate." >>"$GITHUB_STEP_SUMMARY"
-              echo "" >>"$GITHUB_STEP_SUMMARY"
-              echo '```json' >>"$GITHUB_STEP_SUMMARY"
-              cat "$TIMINGS" >>"$GITHUB_STEP_SUMMARY"
-              echo '```' >>"$GITHUB_STEP_SUMMARY"
-          elif [ -f "$REGRESSION" ]; then
-              REGR_COUNT=$(jq -e '.summary.regressions' "$REGRESSION") || REGR_COUNT=0
-              IMPR_COUNT=$(jq -e '.summary.improvements' "$REGRESSION") || IMPR_COUNT=0
-              TOTAL=$(jq -e '.summary.total' "$REGRESSION") || TOTAL=0
-              echo "| Stat | Count |" >>"$GITHUB_STEP_SUMMARY"
-              echo "|------|-------|" >>"$GITHUB_STEP_SUMMARY"
-              echo "| Metrics compared | $TOTAL |" >>"$GITHUB_STEP_SUMMARY"
-              echo "| Regressions | $REGR_COUNT |" >>"$GITHUB_STEP_SUMMARY"
-              echo "| Improvements | $IMPR_COUNT |" >>"$GITHUB_STEP_SUMMARY"
-              echo "" >>"$GITHUB_STEP_SUMMARY"
-              if [ "$REGR_COUNT" -gt 0 ]; then
-                  echo "### Regressions" >>"$GITHUB_STEP_SUMMARY"
-                  echo "" >>"$GITHUB_STEP_SUMMARY"
-                  echo "| Metric | Baseline | Current | Δ | % | Unit |" >>"$GITHUB_STEP_SUMMARY"
-                  echo "|--------|---------:|--------:|--:|--:|------|" >>"$GITHUB_STEP_SUMMARY"
-                  jq -r '.metrics[] | select(.regressed) | "| \(.key) | \(.baseline) | \(.current) | \(.delta) | \(.pct_change)% | \(.unit) |"' \
-                      "$REGRESSION" >>"$GITHUB_STEP_SUMMARY"
-              fi
-          fi
-
-      - name: Cleanup
-        if: always()
-        run: |
-          docker/telemetry/workload/run-full-validation.sh --cleanup 2>/dev/null || true
-
-      - name: Check validation result
-        if: steps.validation.outcome == 'failure'
-        run: |
-          echo "Telemetry validation failed. Check the uploaded reports for details."
-          exit 1

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

@@ -72,11 +72,6 @@ jobs:
         with:
           enable_ccache: false
 
-      # Before any step that uses a build tool, composite actions included.
-      - name: Setup Nix environment
-        if: ${{ matrix.toolchain == 'nix' }}
-        uses: ./.github/actions/setup-nix-env
-
       - name: Print build environment
         uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574
 
@@ -92,9 +87,7 @@ jobs:
         with:
           compiler: ${{ matrix.compiler }}
 
-      # `setup-nix-env` already did this for the Nix toolchain.
       - name: Setup Conan
-        if: ${{ matrix.toolchain != 'nix' }}
         env:
           SANITIZERS: ${{ matrix.sanitizers }}
         uses: ./.github/actions/setup-conan
@@ -113,10 +106,6 @@ jobs:
           log_verbosity: ${{ runner.os == 'Windows' && 'quiet' || 'verbose' }}
           sanitizers: ${{ matrix.sanitizers }}
 
-      - name: Check the Conan cache for Nix store references (Nix toolchain)
-        if: ${{ matrix.toolchain == 'nix' }}
-        run: ./bin/check-nix-store-refs.sh "${CONAN_HOME}"
-
       - name: Log into Conan remote
         if: ${{ github.repository == 'XRPLF/rippled' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
         run: conan remote login "${CONAN_REMOTE_NAME}" "${{ secrets.NEXUS_REMOTE_USERNAME }}" --password "${{ secrets.NEXUS_REMOTE_PASSWORD }}"

.gitignore

@@ -92,6 +92,3 @@ target/
 
 # Rust build directory
 crates/target
-
-# Env. file carrying environmental setup data for local or cloud runs.
-.env.*

API-CHANGELOG.md

@@ -54,8 +54,6 @@ This section contains changes targeting a future version.
 - `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)
-- `gateway_balances`: The `account` and `ident` fields now return an `invalidParams` error if the value is not a string, instead of an `internal` error. [#7655](https://github.com/XRPLF/rippled/pull/7655)
-- `account_lines`: The `peer` field now returns an error if the value is not a string. [#7728](https://github.com/XRPLF/rippled/pull/7728)
 
 ## XRP Ledger server version 3.1.0
 

BUILD.md

@@ -4,14 +4,34 @@
 
 ## Minimum Requirements
 
-For the hardware needed to run a node, see
-[System Requirements](https://xrpl.org/system-requirements.html).
+See [System Requirements](https://xrpl.org/system-requirements.html).
 
-For the software needed to build xrpld, see the
-[environment setup guide](./docs/build/environment.md).
+Building xrpld generally requires Git, Python, Conan, CMake, and a C++
+compiler.
+
+- [Python](https://www.python.org/downloads/)
+- [Conan](https://conan.io/downloads.html)
+- [CMake](https://cmake.org/download/)
+
+You can verify that the required tools are installed and runnable with:
+
+```bash
+./bin/check-tools.sh
+```
+
+`xrpld` is written in the C++23 dialect. The [tested compiler versions][cpp23-support] are:
+
+| Compiler    | Version         |
+| ----------- | --------------- |
+| GCC         | 15.2            |
+| Clang       | 22              |
+| Apple Clang | 21              |
+| MSVC        | 19.44[^windows] |
 
 ## Operating Systems
 
+Please see the [environment setup guide](./docs/build/environment.md) for detailed instructions for all platforms.
+
 ### Linux
 
 The Ubuntu Linux distribution has received the highest level of quality
@@ -27,8 +47,9 @@ CI testing is done in macOS 26 (Tahoe), but the build defaults `CMAKE_OSX_DEPLOY
 
 ### Windows
 
-Windows is used by some engineers for development only, and is not recommended
-for production use.
+Windows is used by some engineers for development only.
+
+[^windows]: Windows is not recommended for production use.
 
 ## Steps
 
@@ -53,25 +74,37 @@ releases](https://github.com/XRPLF/rippled/releases).
 
 ### Set Up Conan
 
-Once your [development environment](./docs/build/environment.md) is ready, set
-Conan up for this repository:
+After you have a [C++ development environment](./docs/build/environment.md) ready with Git, Python,
+Conan, CMake, and a C++ compiler, you may need to set up your Conan profile.
+
+These instructions assume a basic familiarity with Conan and CMake. If you are
+unfamiliar with Conan, then please read [this crash course](./docs/build/conan.md) or the official
+[Getting Started][conan-getting-started] walkthrough.
+
+#### Profiles
+
+We recommend that you install our Conan profiles:
 
 ```bash
-./conan/init.sh
+conan config install conan/profiles/ -tf $(conan config home)/profiles/
 ```
 
-That installs our [`global.conf`](./conan/global.conf), our Conan
-[profiles](./conan/profiles), and the `xrplf` remote that hosts some of our
-dependencies. It honours `CONAN_HOME` and never deletes an existing Conan home,
-so it is safe to re-run — it only overwrites the files it manages.
+You can check your Conan profile by running:
 
-> [!TIP]
-> In the [Nix development shell](./docs/build/nix.md#conan-configuration) this is
-> already done for you: the script runs on entry.
+```bash
+conan profile show
+```
 
-You can inspect the resulting profile with `conan profile show`. If it is not
-suitable for your environment, create a custom profile and pass it to Conan — see
-[Advanced Conan configuration](./docs/build/advanced_conan.md).
+If the default profile is not suitable for your environment, you can create a custom profile and pass it to Conan.
+More information on customizing Conan can be found in the [Advanced Conan configuration](./docs/build/advanced_conan.md).
+
+#### Add xrplf remote
+
+Run the following command to add the `xrplf` remote, which hosts some of our dependencies:
+
+```bash
+conan remote add --index 0 --force xrplf https://conan.xrplf.org/repository/conan/
+```
 
 ### Set Up Ccache
 
@@ -236,14 +269,10 @@ which is only enabled when the `coverage` option is set, e.g. with
 Prerequisites for the coverage report:
 
 - [gcovr tool][gcovr] (can be installed e.g. with [pip][python-pip])
-- `gcov` for GCC or `llvm-cov` for Clang, usually installed with the compiler
+- `gcov` for GCC (installed with the compiler by default) or
+- `llvm-cov` for Clang (installed with the compiler by default)
 - `Debug` build type
 
-> [!NOTE]
-> Clang coverage is not available in the [Nix development shell](./docs/build/nix.md#building-xrpld-in-the-nix-shell):
-> its `clang` shells do not ship `llvm-cov`. Use a `gcc` shell instead (`.#gcc`,
-> or `.#gcc-plain` on Linux), which provides a `gcov` matching its compiler.
-
 A coverage report is created when the following steps are completed, in order:
 
 1. `xrpld` binary built with instrumentation data, enabled by the `coverage`
@@ -304,7 +333,6 @@ See [Sanitizers docs](./docs/build/sanitizers.md) for more details.
 | ---------------- | ------------- | ----------------------------------------------------------------------------- |
 | `assert`         | OFF           | Force enabling assertions.                                                    |
 | `coverage`       | OFF           | Prepare the coverage report.                                                  |
-| `rust`           | OFF           | Build the Rust crates and the C++ code that depends on them.                  |
 | `tests`          | OFF           | Build tests.                                                                  |
 | `unity`          | OFF           | Configure a unity build.                                                      |
 | `verify_headers` | ON            | Make the `verify-headers` target available to compile each header on its own. |
@@ -317,30 +345,6 @@ memory) since they concatenate sources into fewer translation units. Non-unity
 builds may be faster for incremental builds, and can be helpful for detecting
 `#include` omissions.
 
-### Rust crates
-
-The Rust crates in `crates/` are only part of the build when `rust` is ON. With
-`-Drust=OFF` (the default) the `crates` directory is not added to the build, no
-cxxbridge bindings are generated, and the C++ tests that exercise the Rust
-interop are not compiled — so no Rust toolchain is needed. CI builds always pass
-`-Drust=ON`.
-
-With `-Drust=ON` you need one extra dependency: a Rust toolchain (`cargo`,
-`rustc`) matching the channel pinned in
-[`rust-toolchain.toml`](./rust-toolchain.toml), which compiles the crates and
-generates the cxxbridge bindings. It is provided by the
-[Nix development shell](./docs/build/nix.md), so `-Drust=ON` works there without
-any extra setup; otherwise install it as described in
-[Rust](./docs/build/environment.md#rust).
-
-The crates also have their own Rust unit tests. Those are run with `cargo` and
-need only the Rust toolchain, independently of CMake and of the `rust` option
-(CI runs them with `cargo nextest`):
-
-```bash
-cargo test --manifest-path crates/Cargo.toml --workspace
-```
-
 ### Verifying headers
 
 The regular build only compiles `.cpp` files, so a header is only ever checked
@@ -385,14 +389,10 @@ After any updates or changes to dependencies, you may need to do the following:
 4. [Regenerate lockfile](./docs/build/advanced_conan.md#conan-lockfile).
 5. Re-run [conan install](#build-and-test).
 
-If you are using the Nix development shell, whether prebuilt Conan binaries apply
-depends on your platform — see
-[Prebuilt packages](./docs/build/nix.md#prebuilt-packages).
-
 #### ERROR: Package not resolved
 
 If you're seeing an error like `ERROR: Package 'snappy/1.1.10' not resolved: Unable to find 'snappy/1.1.10#968fef506ff261592ec30c574d4a7809%1756234314.246' in remotes.`,
-please [set Conan up](#set-up-conan) so the `xrplf` remote is configured, or re-run `conan export` for [patched recipes](./docs/build/advanced_conan.md#patched-recipes).
+please [add `xrplf` remote](#add-xrplf-remote) or re-run `conan export` for [patched recipes](./docs/build/advanced_conan.md#patched-recipes).
 
 ### `protobuf/port_def.inc` file not found
 
@@ -412,6 +412,7 @@ For example, if you want to build Debug:
 1. For conan install, pass `--settings build_type=Debug`
 2. For cmake, pass `-DCMAKE_BUILD_TYPE=Debug`
 
+[cpp23-support]: https://en.cppreference.com/w/cpp/compiler_support/23
 [conan-getting-started]: https://docs.conan.io/en/latest/getting_started.html
 [unity-build]: https://en.wikipedia.org/wiki/Unity_build
 [gcovr]: https://gcovr.com/en/stable/getting-started.html

CMakeLists.txt

@@ -140,28 +140,6 @@ if(rocksdb)
     target_link_libraries(xrpl_libs INTERFACE RocksDB::rocksdb)
 endif()
 
-# OpenTelemetry distributed tracing (optional).
-# When ON, links against opentelemetry-cpp and defines XRPL_ENABLE_TELEMETRY so
-# that SpanGuard factory methods produce real OTel spans.
-# When OFF, all tracing code compiles to no-ops with zero overhead and
-# opentelemetry-cpp is not needed at all.
-#
-# The value below is temporarily ON so that CI compiles the telemetry code
-# paths while this feature is in review. OFF is the intended shipped default;
-# flipping it back is tracked as a separate change. Do not rely on the current
-# value - select it explicitly with cmake -Dtelemetry=ON|OFF or
-# conan install -o telemetry=True|False.
-#
-# -DXRPL_ENABLE_TELEMETRY=OFF does not turn anything off: that name is only a
-# compile definition added below, not a CMake option, so CMake just lists it as
-# an unused variable at the end of configuration.
-option(telemetry "Enable OpenTelemetry tracing" ON)
-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)
     set(nudb nudb::core)
@@ -180,13 +158,8 @@ if(coverage)
     include(XrplCov)
 endif()
 
-add_custom_target(tidy_prerequisites)
-
-if(rust)
-    add_subdirectory(crates)
-endif()
+add_subdirectory(crates)
 include(XrplCore)
-
 include(XrplProtocolAutogen)
 include(XrplInstall)
 include(XrplValidatorKeys)

CONTRIBUTING.md

@@ -225,9 +225,8 @@ environment, so you don't need to install most of the individual tools
 yourself. The version of each hook sourced from an external repository
 (`clang-format`, `gersemi`, etc.) is pinned in that file, so running the hooks
 locally uses exactly the same versions as CI. A few `local` hooks — most notably
-`clang-tidy` and `cargo fmt` — run tools from your own environment; see
-[Installing clang-tidy](#installing-clang-tidy) and
-[Rust](./docs/build/environment.md#rust) for how to get those.
+`clang-tidy` — run tools from your own environment; see
+[Installing clang-tidy](#installing-clang-tidy) for how to get those.
 
 To get started, install `pre-commit` and enable the git hook scripts:
 
@@ -256,7 +255,6 @@ The hooks configured in this repository include, among others:
 - `clang-tidy` — C++ static analysis (see [Clang-tidy](#clang-tidy)); opt in with `TIDY=1`
 - `fix-include-style`, `fix-pragma-once`, `check-doxygen-style` — C++ hygiene
 - `gersemi` — CMake formatting
-- `cargo fmt` — Rust formatting for the crates in `crates/`
 - `prettier`, `black`, `shfmt` — formatting for JavaScript/JSON/Markdown, Python, and shell
 - `cspell` — spell checking
 
@@ -321,11 +319,7 @@ See the [environment setup guide](./docs/build/environment.md#clang-tidy) for ho
 
 ### Running clang-tidy locally
 
-Before running clang-tidy, you must generate the files it depends on (protobuf headers, and, when the project is configured with `-Drust=ON`, the cxxbridge headers from the Rust crates). Configure the project as described in [`BUILD.md`](./BUILD.md), then build the `tidy_prerequisites` target, which generates all of them:
-
-```bash
-cmake --build build --target tidy_prerequisites
-```
+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)
 
@@ -362,151 +356,6 @@ run-clang-tidy -p build -quiet -fix -format -allow-no-checks src tests
 
 `-format` reformats the fixed code with [`.clang-format`](./.clang-format); without it the fixes are inserted in LLVM style and the `clang-format` hook rewrites them afterwards.
 
-## Telemetry span attribute naming
-
-OpenTelemetry span attribute keys follow these rules so they stay consistent
-across the code, the OTel collector, Tempo, Grafana dashboards, and docs. The
-constants in the `*SpanNames.h` headers are the single source of truth; every
-other layer must match them. A CI check enforces this end to end.
-
-1. Per-span unique attribute: bare field name — allowed when the field is
-   recorded by a single span/workflow, so the span name already supplies the
-   domain (e.g. `command`, `local`, `version` on `rpc.command` / `tx.process`).
-2. Shared attribute (same concept on more than one span): ONE key, reused
-   verbatim on every span that records it — the span name tells the occurrences
-   apart, so no per-emitter prefix is added. Pick the name by the field's
-   meaning: a property of a domain object keeps that object's bare field name
-   (`ledger_hash`, `ledger_seq`, `tx_hash`, `peer_id`, `full_validation`); a
-   field already qualified by a sub-kind keeps that qualifier on every emitter
-   (`proposal_trusted` on both `consensus.proposal.receive` and
-   `peer.proposal.receive`; `validation_trusted` likewise). Define it once in
-   the base `SpanNames.h` `namespace attr` block and re-export (`using`) it from
-   each domain header, so all emitters share the exact string.
-3. Collision qualifier: `<domain>_<field>` — only when a bare name would collide
-   with a DIFFERENT concept in the shared spanmetrics label space, or with the
-   OTel-reserved `status` key (e.g. `rpc_status`, `grpc_status`,
-   `consensus_phase`, `consensus_round`). This disambiguates distinct concepts
-   that share a word; it is NOT used to tag the same concept with the workflow
-   that emitted it — that is rule 2 (one shared name).
-4. Resource attribute: dotted `xrpl.<subsystem>.<field>` — reserved ONLY for
-   process/network identity set once at startup (`xrpl.network.id`,
-   `xrpl.network.type`). Never use the dotted `xrpl.` form for span attributes.
-5. Span names use `<subsystem>[.<component>]` (dotted). Only attribute _keys_
-   follow rules 1–4.
-
-All attribute keys are `lower_snake_case` (lowercase letters, digits, and
-underscores; each dot-separated segment of a resource key likewise). No
-camelCase, uppercase, or spaces.
-
-Standard OpenTelemetry semantic-convention keys keep their canonical dotted
-form (e.g. `service.*` resource attributes, `http.*` span attributes); the
-"no dotted form" rule above applies to xrpl-custom keys, not to OTel-standard
-conventions.
-
-Always reference the `*SpanNames.h` constants for attribute keys and span
-names — never pass a string literal as a key or as a `span`/`childSpan` name
-argument. (Attribute _values_ may be runtime data.)
-
-These rules are enforced by `.github/scripts/otel-naming/check_otel_naming.py`,
-run in CI on every pull request. The check derives the set of valid keys
-directly from the `*SpanNames.h` constants and the resource attributes the code
-registers, so there is no separate list to keep in sync. It cross-validates the
-collector, Tempo, dashboards, and docs against those keys, and each rule runs
-only when the file it needs is present — so it works whether telemetry changes
-land in one pull request or several. Run it locally with:
-
-```
-python .github/scripts/otel-naming/check_otel_naming.py
-```
-
-### Naming a wrong form in prose (`otel-naming:allow-dotted`)
-
-The doc rule (E) flags any dotted `` `xrpl.<domain>.<field>` `` key in the
-telemetry docs, because a reader copies those keys straight into a TraceQL or
-PromQL query. A doc that _teaches_ the convention, or records a rename, has to be
-able to name the wrong form as a counter-example. That mention is opted out with
-a marker naming exactly the keys the line is allowed to mention:
-
-```markdown
-Use `tx_hash`, not `xrpl.tx.hash`.
-<!-- otel-naming:allow-dotted: xrpl.tx.hash -->
-```
-
-- The marker applies to **its own line only**, and exempts **only the keys it
-  lists** (comma- and/or space-separated, backticks optional). A dotted key on a
-  marked line that the marker does not name still fails, so an exemption cannot
-  quietly widen when someone edits the line later.
-- A marker with no key list exempts nothing and reports a warning; so does a
-  marker naming a key the line no longer mentions (a stale exemption).
-- Never use it to keep a real attribute table dotted. If the doc publishes a key
-  an operator is meant to query, fix the key — the marker is for mentions, not
-  for published attributes.
-
-See [.github/scripts/otel-naming/README.md](.github/scripts/otel-naming/README.md)
-for the full rule list.
-
-## Telemetry metric naming
-
-The metric-side counterpart of the span rules above. Metric instrument names and
-metric label keys are duplicated across the emit site, the instrument
-registration, the unit test, `expected_metrics.json`, the dashboard PromQL and
-the runbook, so a rename touches six places and a typo in any one of them fails
-silently at runtime — a metric that never appears, or a label that never joins.
-The constants in the `*MetricNames.h` headers are the single source of truth for
-the C++ layers; a CI check validates the layers that cannot reference a constant.
-
-1. Instrument names are bare `lower_snake_case` with **no `xrpld_` prefix**. The
-   Prometheus exporter adds the namespace itself, so a name carrying it emits
-   `xrpld_xrpld_*` on the wire.
-2. A monotonic counter ends in `_total`, so `rate()` over it reads correctly and
-   a reader can tell it from a gauge at a glance.
-3. A duration carries its unit as the suffix — `_us`, `_ms` or `_seconds`. The
-   unit belongs in the name because the OTel `unit` argument is not surfaced on
-   the Prometheus metric name.
-4. A gauge that snapshots current state takes no suffix (`jobq_saturation`,
-   `sync_state`), and never `_total`.
-5. Label keys are `lower_snake_case` and must have **bounded** cardinality. A
-   multi-series gauge discriminates its readings with the `metric` label rather
-   than minting one instrument per reading.
-6. Label **values** are declared as constants only when the code picks them from
-   a fixed set (`namespace lval`). A value derived from runtime data — a peer
-   address, a ledger hash — must never become a label on a metric.
-
-Always reference the `*MetricNames.h` constants for instrument names and label
-keys — never pass a string literal. (Label _values_ may be runtime data.) Note
-that these headers use `constexpr char[]`, not the `makeStr`/`StaticStr` DSL the
-`*SpanNames.h` headers use: the OTel C++ API takes `nostd::string_view`, which
-constructs from `char const*` but has no constructor from `std::string_view`, so
-`StaticStr` does not compile in an instrument-name or label-key position.
-
-Enforcement is by the same script as the span rules, whose metric rules are:
-
-- **I** — no string literal as an instrument name or label key at an emit site
-  (the mirror of Rule F). Scoped by metric _family_ (the first underscore
-  segment) so conversion can proceed subsystem by subsystem: declaring a
-  constant opts that family in. An unconverted family is reported as a
-  non-fatal **L** warning, keeping the remaining work visible.
-- **J** — the suffix conventions above. The instrument _kind_ is read from the
-  emit site, not guessed from the name, so a multi-series gauge whose units live
-  in its label values is not mistaken for a mis-suffixed duration. A name created
-  through two different factories is reported as a kind conflict rather than a
-  suffix complaint, because no suffix can be correct for both.
-- **K** — every metric named in `docker/telemetry/workload/expected_metrics.json`
-  resolves to a declared constant. This is the check that catches a metric
-  renamed in code while the workload validator still asserts the old name.
-  Groups whose names come from a different emit path (`statsd_gauges`,
-  `statsd_counters` from `beast::insight`, and collector-derived `spanmetrics`)
-  are out of scope by design.
-
-## Adding a new OTel metric
-
-See `src/xrpld/telemetry/MetricMacros.h` for the call-site macros covering every
-OTel instrument kind (Counter, UpDownCounter, Histogram, Gauge, and their
-Observable/async counterparts), `src/xrpld/telemetry/MetricNames.h` for the name
-and label constants to reference (and the rules above), and the "Adding a New
-Metric" section in [docs/telemetry-runbook.md](docs/telemetry-runbook.md) for the
-walkthrough and a need-to-macro lookup table.
-
 ## Contracts and instrumentation
 
 We are using [Antithesis](https://antithesis.com/) for continuous fuzzing,

OpenTelemetryPlan/00-tracing-fundamentals.md

@@ -1,565 +0,0 @@
-# Distributed Tracing Fundamentals
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Next**: [Architecture Analysis](./01-architecture-analysis.md)
-
----
-
-## What is Distributed Tracing?
-
-Distributed tracing is a method for tracking data objects as they flow through distributed systems. In a network like XRP Ledger, a single transaction touches multiple independent nodes—each with no shared memory or logging. Distributed tracing connects these dots.
-
-**Without tracing:** You see isolated logs on each node with no way to correlate them.
-
-**With tracing:** You see the complete journey of a transaction or an event across all nodes it touched.
-
----
-
-## Actors and Actions at a Glance
-
-### Actors
-
-| Who (Plain English)                            | Technical Term  |
-| ---------------------------------------------- | --------------- |
-| A single unit of work being tracked            | Span            |
-| The complete journey of a request              | Trace           |
-| Data that links spans across services          | Trace Context   |
-| Code that creates spans and propagates context | Instrumentation |
-| Service that receives and processes traces     | Collector       |
-| Storage and visualization system               | Backend (Tempo) |
-| Decision logic for which traces to keep        | Sampler         |
-
-### Actions
-
-| What Happens (Plain English)            | Technical Term          |
-| --------------------------------------- | ----------------------- |
-| Start tracking a new operation          | Create a Span           |
-| Connect a child operation to its parent | Set `parent_span_id`    |
-| Group all related operations together   | Share a `trace_id`      |
-| Pass tracking data between services     | Context Propagation     |
-| Decide whether to record a trace        | Sampling (Head or Tail) |
-| Send completed traces to storage        | Export (OTLP)           |
-
----
-
-## 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`       | Identifies the trace             | `event123`                 |
-| `span_id`        | Unique identifier                | `span456`                  |
-| `parent_span_id` | Parent span (if any)             | `p_span123`                |
-| `name`           | Operation name                   | `rpc.submit`               |
-| `start_time`     | When work began (local time)     | `2024-01-15T10:30:00Z`     |
-| `end_time`       | When work completed (local time) | `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
-```
-
-**Reading the diagram:**
-
-- **tx.submit (blue, root)**: The top-level span representing the entire transaction submission; all other spans are its descendants.
-- **tx.validate, tx.relay, tx.apply (green)**: Direct children of tx.submit, representing the three main stages -- validation, relay to peers, and application to the ledger.
-- **ledger.update (red)**: A grandchild span nested under tx.apply, representing the actual ledger state mutation triggered by applying the transaction.
-- **Arrows (parent to child)**: Each arrow indicates a parent-child span relationship where the parent's completion depends on the child finishing.
-
-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   │                         │▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│
-```
-
----
-
-## Span Relationships
-
-Spans don't always form simple parent-child trees. Distributed tracing defines several relationship types to capture different causal patterns:
-
-### 1. Parent-Child (ChildOf)
-
-The default relationship. The parent span **depends on** or **contains** the child span. The child runs within the scope of the parent.
-
-```
-tx.submit (parent)
-├── tx.validate (child)     ← parent waits for this
-├── tx.relay (child)        ← parent waits for this
-└── tx.apply (child)        ← parent waits for this
-```
-
-**When to use:** Synchronous calls, nested operations, any case where the parent's completion depends on the child.
-
-### 2. Follows-From
-
-A causal relationship where the first span **triggers** the second, but does **not wait** for it. The originator fires and moves on.
-
-```
-Time →
-
-tx.receive [=======]
-                     ↓ triggers (follows-from)
-              tx.relay   [===========]   ← runs independently
-```
-
-**When to use:** Asynchronous jobs, queued work, fire-and-forget patterns. For example, a node receives a transaction and queues it for relay — the relay span _follows from_ the receive span but the receiver doesn't wait for relaying to complete.
-
-> **OpenTracing** defined `FollowsFrom` as a first-class reference type alongside `ChildOf`.
-> **OpenTelemetry** represents this using **Span Links** with descriptive attributes instead (see below).
-
-### 3. Span Links (Cross-Trace and Non-Hierarchical)
-
-Links connect spans that are **causally related but not in a parent-child hierarchy**. Unlike parent-child, links can cross trace boundaries.
-
-```
-Trace A                          Trace B
-──────                           ──────
-batch.schedule                   batch.execute
-├─ item.enqueue (span X)    ┌──► process.item
-├─ item.enqueue (span Y) ───┤    (links to X, Y, Z)
-├─ item.enqueue (span Z)    └──►
-```
-
-**Use cases:**
-
-| Pattern              | Description                                                                 |
-| -------------------- | --------------------------------------------------------------------------- |
-| **Batch processing** | A batch span links back to all individual spans that contributed to it      |
-| **Fan-in**           | An aggregation span links to the multiple producer spans it merges          |
-| **Fan-out**          | Multiple downstream spans link back to the single span that triggered them  |
-| **Async handoff**    | A deferred job links back to the request that queued it (follows-from)      |
-| **Cross-trace**      | Correlating spans across independent traces (e.g., retries, related events) |
-
-**Link structure:** Each link carries the target span's context plus optional attributes:
-
-```
-Link {
-    trace_id:   <target trace>
-    span_id:    <target span>
-    attributes: { "link.description": "triggered by batch scheduler" }
-}
-```
-
-### Relationship Summary
-
-```mermaid
-flowchart LR
-    subgraph parent_child["Parent-Child"]
-        direction TB
-        P["Parent"] --> C["Child"]
-    end
-
-    subgraph follows_from["Follows-From"]
-        direction TB
-        A["Span A"] -.->|triggers| B["Span B"]
-    end
-
-    subgraph links["Span Links"]
-        direction TB
-        X["Span X\n(Trace 1)"] -.-|link| Y["Span Y\n(Trace 2)"]
-    end
-
-    parent_child ~~~ follows_from ~~~ links
-
-    style P fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style C fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style A fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style B fill:#bf360c,stroke:#8c2809,color:#ffffff
-    style X fill:#4a148c,stroke:#38006b,color:#ffffff
-    style Y fill:#4a148c,stroke:#38006b,color:#ffffff
-```
-
-| Relationship     | Same Trace? | Dependency?                | OTel Mechanism    |
-| ---------------- | ----------- | -------------------------- | ----------------- |
-| **Parent-Child** | Yes         | Parent depends on child    | `parent_span_id`  |
-| **Follows-From** | Usually     | Causal but no dependency   | Link + attributes |
-| **Span Link**    | Either      | Correlation, no dependency | Link + attributes |
-
----
-
-## Trace ID Generation
-
-A `trace_id` is a 128-bit (16-byte) identifier that groups all spans belonging to one logical operation. How it's generated determines how easily you can find and correlate traces later.
-
-### General Approaches
-
-#### 1. Random (W3C Default)
-
-Generate a random 128-bit ID when a trace starts. Standard approach for most services.
-
-```
-trace_id = random_128_bits()
-```
-
-| Pros                        | Cons                                          |
-| --------------------------- | --------------------------------------------- |
-| Simple, standard            | No natural correlation to domain events       |
-| Guaranteed unique per trace | If propagation is lost, trace is broken       |
-| Works with all OTel tooling | "Find trace for TX abc" requires index lookup |
-
-#### 2. Deterministic (Derived from Domain Data)
-
-Compute the trace_id from a hash of a natural identifier. Every node independently derives the **same** trace_id for the same event.
-
-```
-trace_id = SHA-256(domain_identifier)[0:16]   // truncate to 128 bits
-```
-
-| Pros                                                | Cons                                                       |
-| --------------------------------------------------- | ---------------------------------------------------------- |
-| Propagation-resilient — same ID computed everywhere | Same event processed twice (retry) shares trace_id         |
-| Natural search — domain ID maps directly to trace   | Non-standard (tooling assumes random)                      |
-| No coordination needed between nodes                | 256→128 bit truncation (collision risk negligible at ~2⁶⁴) |
-
-#### 3. Hybrid (Deterministic Prefix + Random Suffix)
-
-First 8 bytes derived from domain data, last 8 bytes random.
-
-```
-trace_id = SHA-256(domain_identifier)[0:8] || random_64_bits()
-```
-
-| Pros                                        | Cons                                     |
-| ------------------------------------------- | ---------------------------------------- |
-| Prefix search: "find all traces for TX abc" | Must propagate to maintain full trace_id |
-| Unique per processing instance              | More complex generation logic            |
-| Retries get distinct trace_ids              | Partial correlation only (prefix match)  |
-
-### XRPL Workflow Analysis
-
-XRPL has a unique advantage: its core workflows produce **globally unique 256-bit hashes** that are known on every node. This makes deterministic trace_id generation practical in ways most systems can't achieve.
-
-#### Natural Identifiers by Workflow
-
-| Workflow            | Natural Identifier                | Size       | Known at Start?               | Same on All Nodes?               |
-| ------------------- | --------------------------------- | ---------- | ----------------------------- | -------------------------------- |
-| **Transaction**     | Transaction hash (`tid_`)         | 256-bit    | Yes — computed before signing | Yes — hash of canonical tx data  |
-| **Consensus round** | Previous ledger hash + ledger seq | 256+32 bit | Yes — known when round opens  | Yes — all validators agree       |
-| **Validation**      | Ledger hash being validated       | 256-bit    | Yes — from consensus result   | Yes — same closed ledger         |
-| **Ledger catch-up** | Target ledger hash                | 256-bit    | Yes — we know what to fetch   | Yes — identifies ledger globally |
-
-#### Where These Identifiers Live in Code
-
-```
-Transaction:     STTx::getTransactionID()     → uint256 tid_
-                 TMTransaction::rawTransaction → recompute hash from bytes
-
-Consensus:       ConsensusProposal::prevLedger_ → uint256 (previous ledger hash)
-                 ConsensusProposal::position_   → uint256 (TxSet hash)
-                 LedgerHeader::seq              → uint32_t (ledger sequence)
-
-Validation:      STValidation::getLedgerHash()  → uint256
-                 STValidation::getNodeID()      → NodeID (160-bit)
-
-Ledger fetch:    InboundLedger constructor      → uint256 hash, uint32_t seq
-                 TMGetLedger::ledgerHash        → bytes (uint256)
-```
-
-### Recommended Strategy: Workflow-Scoped Deterministic
-
-Each workflow type derives its trace_id from its natural domain identifier:
-
-```
-Transaction trace:   trace_id = SHA-256("tx"    || tx_hash)[0:16]
-Consensus trace:     trace_id = SHA-256("cons"  || prev_ledger_hash || ledger_seq)[0:16]
-Ledger catch-up:     trace_id = SHA-256("fetch" || target_ledger_hash)[0:16]
-```
-
-The string prefix (`"tx"`, `"cons"`, `"fetch"`) prevents collisions between workflows that might share underlying hashes.
-
-**Why this works for XRPL:**
-
-1. **Propagation-resilient** — Even if a P2P message drops trace context, every node independently computes the same trace_id from the same tx_hash or ledger_hash. Spans still correlate.
-
-2. **Zero-cost search** — "Show me the trace for transaction ABC" becomes a direct lookup: compute `SHA-256("tx" || ABC)[0:16]` and query. No secondary index needed.
-
-3. **Cross-workflow linking via Span Links** — A consensus trace links to individual transaction traces. A validation span links to the consensus trace. This connects the full picture without forcing everything into one giant trace.
-
-### Cross-Workflow Correlation
-
-Each workflow gets its own trace. Span Links tie them together:
-
-```mermaid
-flowchart TB
-    subgraph tx_trace["Transaction Trace"]
-        direction LR
-        Tn["trace_id = f(tx_hash)"]:::note --> T1["tx.receive"] --> T2["tx.validate"] --> T3["tx.relay"]
-    end
-
-    subgraph cons_trace["Consensus Trace"]
-        direction LR
-        Cn["trace_id = f(prev_ledger, seq)"]:::note --> C1["cons.open"] --> C2["cons.propose"] --> C3["cons.accept"]
-    end
-
-    subgraph val_trace["Validation"]
-        direction LR
-        Vn["spans within consensus trace"]:::note --> V1["val.create"] --> V2["val.broadcast"]
-    end
-
-    subgraph fetch_trace["Catch-Up Trace"]
-        direction LR
-        Fn["trace_id = f(ledger_hash)"]:::note --> F1["fetch.request"] --> F2["fetch.receive"] --> F3["fetch.apply"]
-    end
-
-    C1 -.-|"span link\n(tx traces)"| T3
-    C3 --> V1
-    F1 -.-|"span link\n(target ledger)"| C3
-
-    classDef note fill:none,stroke:#888,stroke-dasharray:5 5,color:#333,font-style:italic
-    style T1 fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style T2 fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style T3 fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style C1 fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style C2 fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style C3 fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style V1 fill:#bf360c,stroke:#8c2809,color:#ffffff
-    style V2 fill:#bf360c,stroke:#8c2809,color:#ffffff
-    style F1 fill:#4a148c,stroke:#38006b,color:#ffffff
-    style F2 fill:#4a148c,stroke:#38006b,color:#ffffff
-    style F3 fill:#4a148c,stroke:#38006b,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **Transaction Trace (blue)**: An independent trace whose `trace_id` is deterministically derived from the transaction hash. Contains receive, validate, and relay spans.
-- **Consensus Trace (green)**: An independent trace whose `trace_id` is derived from the previous ledger hash and sequence number. Covers the open, propose, and accept phases.
-- **Validation (red)**: Validation spans live within the consensus trace (not a separate trace). They are created after the accept phase completes.
-- **Catch-Up Trace (purple)**: An independent trace for ledger acquisition, derived from the target ledger hash. Used when a node is behind and fetching missing ledgers.
-- **Dotted arrows (span links)**: Cross-trace correlations. Consensus links to transaction traces it included; catch-up links to the consensus trace that produced the target ledger.
-- **Solid arrow (C3 to V1)**: A parent-child relationship -- validation spans are direct children of the consensus accept span within the same trace.
-
-**How a query flows:**
-
-```
-"Why was TX abc slow?"
-  1. Compute trace_id = SHA-256("tx" || abc)[0:16]
-  2. Find transaction trace → see it was included in consensus round N
-  3. Follow span link → consensus trace for round N
-  4. See which phase was slow (propose? accept?)
-  5. If a node was catching up, follow link → catch-up trace
-```
-
-### Trade-offs to Consider
-
-| Concern                       | Mitigation                                                                                                                    |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| **Retries get same trace_id** | Add `attempt` attribute to root span; spans have unique span_ids and timestamps                                               |
-| **256→128 bit truncation**    | Birthday-bound collision at ~2⁶⁴ operations — negligible for XRPL's throughput                                                |
-| **Non-standard generation**   | OTel spec allows any 16-byte non-zero value; tooling works on the hex string                                                  |
-| **Hash computation cost**     | SHA-256 is ~0.3μs per call; XRPL already computes these hashes for other purposes                                             |
-| **Late-binding identifiers**  | Ledger hash isn't known until after consensus — validation spans use ledger_seq as fallback, then link to the consensus trace |
-
----
-
-## Distributed Traces Across Nodes
-
-In distributed systems like xrpld, 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
-```
-
-**Reading the diagram:**
-
-- **Client**: The external entity that submits a transaction. It does not carry trace context -- the trace originates at the first node.
-- **Node A**: The entry point that creates a new trace (trace_id: abc123) and the root span `tx.receive`. It relays the transaction to peers with trace context attached.
-- **Node B and Node C**: Peer nodes that receive the relayed transaction along with the propagated trace context. Each creates a child span under Node A's span, preserving the same `trace_id`.
-- **Arrows with trace context**: The relay messages carry `trace_id` and `parent_span_id`, allowing each downstream node to link its spans back to the originating span on Node A.
-
----
-
-## Context Propagation
-
-For traces to work across nodes, **trace context must be propagated** in messages.
-
-### What's in the Context (~26 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` | 1 byte   | Sampling decision (bit 0 = sampled; bits 1-7 reserved)  |
-| `trace_state` | variable | Optional vendor-specific data (typically omitted)       |
-
-### 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-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
-             │  │                                │                │
-             │  │                                │                └── Flags (sampled)
-             │  │                                └── Parent span ID (16 hex)
-             │  └── Trace ID (32 hex)
-             └── Version
-```
-
-### Protocol Buffers (xrpld P2P messages)
-
-xrpld P2P messages such as `TMTransaction` carry the trace context in two added byte fields alongside the existing payload: `trace_parent` holds the W3C traceparent (`trace_id`, `span_id`, and `trace_flags`), and `trace_state` holds the optional W3C tracestate. Together they propagate the trace across the P2P boundary so a receiving node can attach its spans to the sender's span.
-
----
-
-## Sampling
-
-Not every trace needs to be recorded. **Sampling** reduces overhead:
-
-### Head Sampling (at trace start)
-
-```
-Request arrives → Random N% chance → Record or skip entire trace
-```
-
-- ✅ Low overhead
-- ❌ May miss interesting traces
-
-> **xrpld note**: xrpld intentionally fixes head sampling at 100% (sample
-> everything) and does not expose a configurable ratio. A per-node ratio
-> would let different nodes make divergent keep/drop decisions for the same
-> distributed trace, producing broken/partial traces. xrpld uses a
-> `ParentBased` sampler so spans with a remote parent honor the upstream
-> decision. Volume reduction is delegated to collector-side tail sampling.
-
-### 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 xrpld
-
-| 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                                     |
-| **Parent-Child**     | Span relationship where the parent depends on the child             |
-| **Follows-From**     | Causal relationship where originator doesn't wait for the result    |
-| **Span Link**        | Non-hierarchical connection between spans, possibly across traces   |
-| **Deterministic ID** | Trace ID derived from domain data (e.g., tx_hash) instead of random |
-| **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 (Tempo)                                |
-| **Head Sampling**    | Sampling decision at trace start                                    |
-| **Tail Sampling**    | Sampling decision after trace completes                             |
-
----
-
-_Next: [Architecture Analysis](./01-architecture-analysis.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/01-architecture-analysis.md

@@ -1,467 +0,0 @@
-# Architecture Analysis
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Design Decisions](./02-design-decisions.md) | [Implementation Strategy](./03-implementation-strategy.md)
-
----
-
-## 1.1 Current xrpld Architecture Overview
-
-> **WS** = WebSocket | **UNL** = Unique Node List | **TxQ** = Transaction Queue | **StatsD** = Statistics Daemon
-
-The xrpld node software consists of several interconnected components that need instrumentation for distributed tracing:
-
-```mermaid
-flowchart TB
-    subgraph xrpld["xrpld Node"]
-        subgraph services["Core Services"]
-            RPC["RPC Server<br/>(HTTP/WS/gRPC)"]
-            Overlay["Overlay<br/>(P2P Network)"]
-            Consensus["Consensus<br/>(RCLConsensus)"]
-            ValidatorList["ValidatorList<br/>(UNL Mgmt)"]
-        end
-
-        JobQueue["JobQueue<br/>(Thread Pool)"]
-
-        subgraph processing["Processing Layer"]
-            NetworkOPs["NetworkOPs<br/>(Tx Processing)"]
-            LedgerMaster["LedgerMaster<br/>(Ledger Mgmt)"]
-            NodeStore["NodeStore<br/>(Database)"]
-            InboundLedgers["InboundLedgers<br/>(Ledger Sync)"]
-        end
-
-        subgraph appservices["Application Services"]
-            PathFind["PathFinding<br/>(Payment Paths)"]
-            TxQ["TxQ<br/>(Fee Escalation)"]
-            LoadMgr["LoadManager<br/>(Fee/Load)"]
-        end
-
-        subgraph observability["Existing Observability"]
-            PerfLog["PerfLog<br/>(JSON)"]
-            Insight["Insight<br/>(StatsD)"]
-            Logging["Logging<br/>(Journal)"]
-        end
-
-        services --> JobQueue
-        JobQueue --> processing
-        JobQueue --> appservices
-    end
-
-    style xrpld fill:#424242,stroke:#212121,color:#ffffff
-    style services fill:#1565c0,stroke:#0d47a1,color:#ffffff
-    style processing fill:#2e7d32,stroke:#1b5e20,color:#ffffff
-    style appservices fill:#6a1b9a,stroke:#4a148c,color:#ffffff
-    style observability fill:#e65100,stroke:#bf360c,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **Core Services (blue)**: The entry points into xrpld -- RPC Server handles client requests, Overlay manages peer-to-peer networking, Consensus drives agreement, and ValidatorList manages trusted validators.
-- **JobQueue (center)**: The asynchronous thread pool that decouples Core Services from the Processing and Application layers. All work flows through it.
-- **Processing Layer (green)**: Core business logic -- NetworkOPs processes transactions, LedgerMaster manages ledger state, NodeStore handles persistence, and InboundLedgers synchronizes missing data.
-- **Application Services (purple)**: Higher-level features -- PathFinding computes payment routes, TxQ manages fee-based queuing, and LoadManager tracks server load.
-- **Existing Observability (orange)**: The current monitoring stack (PerfLog, Insight, Journal logging) that OpenTelemetry will complement, not replace.
-- **Arrows (Services to JobQueue to layers)**: Work originates at Core Services, is enqueued onto the JobQueue, and dispatched to Processing or Application layers for execution.
-
----
-
-## 1.1.1 Actors and Actions
-
-### Actors
-
-| Who (Plain English)                       | Technical Term             |
-| ----------------------------------------- | -------------------------- |
-| Network node running XRPL software        | xrpld node                 |
-| External client submitting requests       | RPC Client                 |
-| Network neighbor sharing data             | Peer (PeerImp)             |
-| Request handler for client queries        | RPC Server (ServerHandler) |
-| Command executor for specific RPC methods | RPCHandler                 |
-| Agreement process between nodes           | Consensus (RCLConsensus)   |
-| Transaction processing coordinator        | NetworkOPs                 |
-| Background task scheduler                 | JobQueue                   |
-| Ledger state manager                      | LedgerMaster               |
-| Payment route calculator                  | PathFinding (Pathfinder)   |
-| Transaction waiting room                  | TxQ (Transaction Queue)    |
-| Fee adjustment system                     | LoadManager                |
-| Trusted validator list manager            | ValidatorList              |
-| Protocol upgrade tracker                  | AmendmentTable             |
-| Ledger state hash tree                    | SHAMap                     |
-| Persistent key-value storage              | NodeStore                  |
-
-### Actions
-
-| What Happens (Plain English)                   | Technical Term         |
-| ---------------------------------------------- | ---------------------- |
-| Client sends a request to a node               | `rpc.request`          |
-| Node executes a specific RPC command           | `rpc.command.*`        |
-| Node receives a transaction from a peer        | `tx.receive`           |
-| Node checks if a transaction is valid          | `tx.validate`          |
-| Node forwards a transaction to neighbors       | `tx.relay`             |
-| Nodes agree on which transactions to include   | `consensus.round`      |
-| Consensus progresses through phases            | `consensus.phase.*`    |
-| Node builds a new confirmed ledger             | `ledger.build`         |
-| Node fetches missing ledger data from peers    | `ledger.acquire`       |
-| Node computes payment routes                   | `pathfind.compute`     |
-| Node queues a transaction for later processing | `txq.enqueue`          |
-| Node increases fees due to high load           | `fee.escalate`         |
-| Node fetches the latest trusted validator list | `validator.list.fetch` |
-| Node votes on a protocol amendment             | `amendment.vote`       |
-| Node synchronizes state tree data              | `shamap.sync`          |
-
----
-
-## 1.2 Key Components for Instrumentation
-
-> **TxQ** = Transaction Queue | **UNL** = Unique Node List
-
-| 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                 |
-| **PathFinding**    | `src/xrpld/app/paths/`                     | Payment path computation | Path latency, cache hits         |
-| **TxQ**            | `src/xrpld/app/misc/TxQ.cpp`               | Transaction queue/fees   | Queue depth, eviction rates      |
-| **LoadManager**    | `src/xrpld/app/main/LoadManager.cpp`       | Fee escalation/load      | Fee levels, load factors         |
-| **InboundLedgers** | `src/xrpld/app/ledger/InboundLedgers.cpp`  | Ledger acquisition       | Sync time, peer reliability      |
-| **ValidatorList**  | `src/xrpld/app/misc/ValidatorList.cpp`     | UNL management           | List freshness, fetch failures   |
-| **AmendmentTable** | `src/xrpld/app/misc/AmendmentTable.cpp`    | Protocol amendments      | Voting status, activation events |
-| **SHAMap**         | `src/xrpld/shamap/`                        | State hash tree          | Sync speed, missing nodes        |
-
----
-
-## 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)
-```
-
-**Reading the diagram:**
-
-- **Client**: The external entity that submits a transaction to Peer A. It has no trace context -- the trace starts at the first node.
-- **Peer A (Receive)**: The entry node that creates the root span `tx.receive`, runs HashRouter deduplication to avoid processing duplicates, and creates a child `tx.validate` span.
-- **Peer A to Peer B arrow**: The relay message carries trace context (trace_id + parent span_id), enabling Peer B to create a linked span under the same trace.
-- **Peer B (Relay)**: Receives the transaction and trace context, creates a `tx.receive` span linked to Peer A's trace, then relays onward.
-- **Peer C (Validate)**: Final hop in this example. Creates a linked `tx.receive` span and runs `tx.process` to fully process the transaction.
-- **Blue rectangles**: Highlight the span boundaries on each node, showing where instrumentation creates and closes spans.
-
-### 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/>ledger_seq = 12345678<br/>consensus_mode = proposing<br/>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
-```
-
-**Reading the diagram:**
-
-- **consensus.round (orange, root span)**: The top-level span encompassing the entire consensus round, with attributes like ledger sequence, mode, and proposer count.
-- **consensus.phase.open (blue)**: The first phase where the node waits (~3s) to collect incoming transactions before proposing.
-- **consensus.phase.establish (green)**: The negotiation phase where validators exchange proposals, resolve disputes, and converge on a transaction set. Child spans track each proposal received/sent and each dispute resolved.
-- **consensus.phase.accept (pink)**: The final phase where the agreed transaction set is applied, a new ledger is built, and the ledger is validated. Child spans cover `ledger.build` and `ledger.validate`.
-- **Arrows (open to establish to accept)**: The sequential flow through the three consensus phases. Each phase must complete before the next begins.
-
----
-
-## 1.5 RPC Request Flow
-
-> **WS** = WebSocket
-
-RPC requests support W3C Trace Context headers for distributed tracing across services:
-
-```mermaid
-flowchart TB
-    subgraph request["rpc.request (root span)"]
-        http["HTTP Request — POST /<br/>traceparent:<br/>00-abc123...-def456...-01"]
-
-        attrs["Attributes:<br/>http.method = POST<br/>net.peer.ip = 192.168.1.100<br/>command = submit"]
-
-        subgraph enqueue["jobqueue.enqueue"]
-            job_attr["job_type = jtCLIENT_RPC"]
-        end
-
-        subgraph command["rpc.command.submit"]
-            cmd_attrs["version = 2<br/>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
-```
-
-**Reading the diagram:**
-
-- **rpc.request (green, root span)**: The outermost span representing the full RPC request lifecycle, from HTTP receipt to response. Carries the W3C `traceparent` header for distributed tracing.
-- **HTTP Request node**: Shows the incoming POST request with its `traceparent` header and extracted attributes (method, peer IP, command name).
-- **jobqueue.enqueue (blue)**: The span covering the asynchronous handoff from the RPC thread to the JobQueue worker thread. The trace context is preserved across this async boundary.
-- **rpc.command.submit (orange)**: The span for the actual command execution, with child spans for deserialization, local validation, and network submission.
-- **Response node**: The final output with HTTP status and total duration, marking the end of the root span.
-- **Arrows (top to bottom)**: The sequential processing pipeline -- receive request, extract attributes, enqueue job, execute command, return response.
-
----
-
-## 1.6 Key Trace Points
-
-> **TxQ** = Transaction Queue
-
-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     |
-| **PathFinding** | `pathfind.request`     | `PathRequest.cpp`      | `doUpdate()`            | High     |
-| **PathFinding** | `pathfind.compute`     | `Pathfinder.cpp`       | `findPaths()`           | High     |
-| **TxQ**         | `txq.enqueue`          | `TxQ.cpp`              | `apply()`               | High     |
-| **TxQ**         | `txq.apply`            | `TxQ.cpp`              | `processClosedLedger()` | High     |
-| **Fee**         | `fee.escalate`         | `LoadManager.cpp`      | `raiseLocalFee()`       | Medium   |
-| **Ledger**      | `ledger.replay`        | `LedgerReplayer.h`     | `replay()`              | Medium   |
-| **Ledger**      | `ledger.delta`         | `LedgerDeltaAcquire.h` | `processData()`         | Medium   |
-| **Validator**   | `validator.list.fetch` | `ValidatorList.cpp`    | `verify()`              | Medium   |
-| **Validator**   | `validator.manifest`   | `Manifest.cpp`         | `applyManifest()`       | Low      |
-| **Amendment**   | `amendment.vote`       | `AmendmentTable.cpp`   | `doVoting()`            | Low      |
-| **SHAMap**      | `shamap.sync`          | `SHAMap.cpp`           | `fetchRoot()`           | Medium   |
-
----
-
-## 1.7 Instrumentation Priority
-
-> **TxQ** = Transaction Queue
-
-```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.2, 0.92]
-    Transaction Tracing: [0.55, 0.88]
-    Consensus Tracing: [0.78, 0.82]
-    PathFinding: [0.38, 0.75]
-    TxQ and Fees: [0.25, 0.65]
-    Ledger Sync: [0.62, 0.58]
-    Peer Message Tracing: [0.35, 0.25]
-    JobQueue Tracing: [0.2, 0.48]
-    Validator Mgmt: [0.48, 0.42]
-    Amendment Tracking: [0.15, 0.32]
-    SHAMap Operations: [0.72, 0.45]
-```
-
----
-
-## 1.8 Observable Outcomes
-
-> **TxQ** = Transaction Queue | **UNL** = Unique Node List
-
-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="xrpld" && tx_hash="ABC123..."}` |
-| **Cross-Node Propagation** | Transaction path across multiple xrpld nodes with timing                                    | `{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                                          | `{command="account_info"}`                      |
-| **Ledger Acquisition**     | Peer-to-peer ledger data requests and responses                                             | `{span.name="ledger.acquire"}`                  |
-| **PathFinding Latency**    | Path computation time and cache effectiveness for payment RPCs                              | `{span.name="pathfind.compute"}`                |
-| **TxQ Behavior**           | Queue depth, eviction patterns, fee escalation during congestion                            | `{span.name=~"txq.*"}`                          |
-| **Ledger Sync**            | Full acquisition timeline including delta and transaction fetches                           | `{span.name=~"ledger.acquire.*"}`               |
-| **Validator Health**       | UNL fetch success, manifest updates, stale list detection                                   | `{span.name=~"validator.*"}`                    |
-
-### 1.8.2 What You Will See: Metrics (Derived from Traces)
-
-| 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           |
-| **PathFinding Latency**       | Path computation time per currency pair | Heatmap by currency         |
-| **TxQ Depth**                 | Queued transactions over time           | Time series with thresholds |
-| **Fee Escalation Level**      | Current fee multiplier                  | Gauge with alert thresholds |
-| **Ledger Sync Duration**      | Time to acquire missing ledgers         | Histogram                   |
-
-### 1.8.3 Concrete Dashboard Examples
-
-**Transaction Trace View (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.4, 2.8, 3.2, 3.8, 4.3, 4.5, 5.0, 4.7, 4.0, 3.2, 2.6, 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                          |
-| **Path Computation Slow** | pathfind.compute span shows high latency; cache miss rate in attributes      | Warm the RippleLineCache, check order book depth |
-| **TxQ Full**              | txq.enqueue spans show evictions; fee.escalate spans increasing              | Monitor fee levels, alert operators              |
-| **Ledger Sync Stalled**   | ledger.acquire spans timing out; peer reliability attributes show issues     | Check peer connectivity, add trusted peers       |
-| **UNL Stale**             | validator.list.fetch spans failing; last_update attribute aging              | Verify validator site URLs, check DNS            |
-
-### 1.8.5 Developer Debugging Workflow
-
-1. **Find Transaction**: Query by `tx_hash` to get full trace
-2. **Identify Bottleneck**: Look at span durations to find slowest component
-3. **Check Attributes**: Review `validity`, `rpc_status` for errors
-4. **Correlate Logs**: Use `trace_id` to find related PerfLog entries
-5. **Compare Nodes**: Filter by `service.instance.id` to compare behavior across nodes
-
----
-
-_Next: [Design Decisions](./02-design-decisions.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/02-design-decisions.md

@@ -1,866 +0,0 @@
-# Design Decisions
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Architecture Analysis](./01-architecture-analysis.md)
-
----
-
-## 2.1 OpenTelemetry Components
-
-> **OTLP** = OpenTelemetry Protocol
-
-### 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_http_exporter` | OTLP/HTTP export       | Yes (shipped in Phase 1b) |
-| `opentelemetry-cpp::otlp_grpc_exporter` | OTLP/gRPC export       | Future (not yet wired up) |
-
-### 2.1.2 Instrumentation Strategy
-
-**Manual Instrumentation** (recommended):
-
-| Approach   | Pros                                                            | Cons                                                    |
-| ---------- | --------------------------------------------------------------- | ------------------------------------------------------- |
-| **Manual** | Precise control, optimized placement, xrpld-specific attributes | More development effort                                 |
-| **Auto**   | Less code, automatic coverage                                   | Less control, potential overhead, limited customization |
-
----
-
-## 2.2 Exporter Configuration
-
-> **OTLP** = OpenTelemetry Protocol
-
-```mermaid
-flowchart TB
-    subgraph nodes["xrpld Nodes"]
-        node1["xrpld<br/>Node 1"]
-        node2["xrpld<br/>Node 2"]
-        node3["xrpld<br/>Node 3"]
-    end
-
-    collector["OpenTelemetry<br/>Collector<br/>(sidecar or standalone)"]
-
-    subgraph backends["Observability Backends"]
-        tempo["Tempo"]
-        elastic["Elastic<br/>APM"]
-    end
-
-    node1 -->|"OTLP/HTTP<br/>:4318"| collector
-    node2 -->|"OTLP/HTTP<br/>:4318"| collector
-    node3 -->|"OTLP/HTTP<br/>:4318"| collector
-
-    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
-```
-
-**Reading the diagram:**
-
-- **xrpld Nodes (blue)**: The source of telemetry data. Each xrpld node exports spans via OTLP/HTTP on port 4318 (the only exporter shipped in Phase 1b).
-- **OpenTelemetry Collector (red)**: The central aggregation point that receives spans from all nodes. Can run as a sidecar (per-node) or standalone (shared). Handles batching, filtering, and routing.
-- **Observability Backends (green)**: The storage and visualization destinations. Tempo is the recommended backend for both development and production, and Elastic APM is an alternative. The Collector routes to one or more backends.
-- **Arrows (nodes to collector to backends)**: The data pipeline -- spans flow from nodes to the Collector over HTTP, then the Collector fans out to the configured backends.
-
-### 2.2.1 OTLP/HTTP (Shipped in Phase 1b)
-
-OTLP/HTTP is the only exporter wired up in Phase 1b. It is configured via
-`OtlpHttpExporterOptions` with the collector traces endpoint
-(`http://localhost:4318/v1/traces` by default) and a JSON content type
-(binary protobuf is also available).
-
-### 2.2.2 OTLP/gRPC (Future Work — Planned Upgrade)
-
-OTLP/gRPC is planned as a future upgrade from the HTTP exporter. The gRPC
-transport offers lower per-span overhead and tighter back-pressure semantics
-than HTTP/JSON, making it attractive for production deployments once the HTTP
-path is validated in earlier phases.
-
-Required to land this upgrade:
-
-1. Add `opentelemetry-cpp::otlp_grpc_exporter` to the Conan recipe (the
-   dependency already exists but is not linked in Phase 1b builds).
-2. Extend `TelemetryConfig.cpp` to parse an `exporter` key (`otlp_http`
-   default, `otlp_grpc` opt-in) and a gRPC endpoint override.
-3. In `Telemetry::start()` branch on the parsed exporter type and construct
-   either `OtlpHttpExporterFactory::Create(httpOpts)` or
-   `OtlpGrpcExporterFactory::Create(grpcOpts)` accordingly.
-4. Update the runbook and dashboards to document the alternate port and TLS
-   settings.
-
-When wired up, the gRPC path will use `OtlpGrpcExporterOptions` configured with
-the collector endpoint (host on port 4317), TLS credentials enabled, and a CA
-certificate path.
-
-Until that work lands, `OtlpGrpcExporterOptions` is **not** used by any code
-path in Phase 1b through Phase 5.
-
----
-
-## 2.3 Span Naming Conventions
-
-> **TxQ** = Transaction Queue | **UNL** = Unique Node List | **WS** = WebSocket
-
-### 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
-
-> **Status column.** This catalog is the design inventory; it is not a
-> statement of what currently emits. `Live` means the span is present in the
-> implemented inventory ([09-data-collection-reference.md §1.1](./09-data-collection-reference.md#11-complete-span-inventory-41-spans)),
-> which is the authoritative list. `Renamed`/`Split` means the concept shipped
-> under a different name than planned here. **Not built** means no span is
-> emitted for it today.
->
-> **"Not built" is not one thing.** All 14 such entries fall into three cases, and the
-> fourth column says which — filing them all as oversights would be wrong:
->
-> - **Superseded by metrics or logs (7)** — a deliberate trade-off: the signal is already
->   carried by a metric or by a log-derived panel, and a span would add per-event volume
->   without adding information. `tx.relay`, `fee.escalate`, `validator.list.fetch`,
->   `validator.manifest`, `shamap.sync`, `job.enqueue`, `job.execute`.
-> - **Gap (6)** — nothing was decided; they were simply never instrumented. The four
->   `peer.*` entries, plus `ledger.replay` and `ledger.delta` — and those last two are the
->   sharpest, because they have **no metric substitute at all**.
-> - **Deferred (1)** — scheduled work: `amendment.vote` (Phase 11).
->
-> The four `peer.*` entries are the peer-span coverage gap: only
-> `peer.proposal.receive` and `peer.validation.receive` exist, so protocol
-> message send/receive and connection lifecycle are untraced. See
-> [09 §6.4](./09-data-collection-reference.md#64-peer-span-coverage-gap-not-implemented).
->
-> `tx.validate` did ship, but renamed and split three ways: the apply pipeline
-> traces `tx.preflight` (stateless checks), `tx.preclaim` (ledger-state checks)
-> and `tx.transactor` (application), each stamped with a `stage` attribute.
-> Names come from `TxApplySpanNames.h:90,94,99`. The spans are created in two
-> different files, not one: `tx.preflight` and `tx.preclaim` come from
-> `applySteps.cpp` (`invokePreflight()` at `:211-212`, `invokePreclaim()` at
-> `:258-261`, both via the shared `makeStageSpan()` helper at `:89-126`), while
-> `tx.transactor` is created in `Transactor::operator()()`
-> (`Transactor.cpp:1601-1605`). Query them with
-> `name=~"tx\.(preflight|preclaim|transactor)"` — a **single** backslash; RE2
-> reads `\\.` as a literal backslash followed by any character, which matches
-> nothing here — never `name="tx.validate"`.
-
-| Span name                      | Description                             | Status                                                           | Why not built / where the signal lives instead                                                                                                                                                                                                                                                             |
-| ------------------------------ | --------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tx.receive`                   | Transaction received from network       | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `tx.validate`                  | Transaction signature/format validation | Renamed + split → `tx.preflight`, `tx.preclaim`, `tx.transactor` | —                                                                                                                                                                                                                                                                                                          |
-| `tx.process`                   | Full transaction processing             | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `tx.relay`                     | Transaction relay to peers              | **Not built**                                                    | **Superseded by metrics.** Relay volume is carried by the overlay traffic counters (`total_bytes_in/out`, `total_messages_in/out`, per-`TrafficCount` category). Relay is also per-peer fan-out, so one span per relay multiplies by peer count for data the counters already aggregate.                   |
-| `tx.apply`                     | Apply transaction to ledger             | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.round`              | Complete consensus round                | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.phase.open`         | Open phase - collecting transactions    | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.phase.establish`    | Establish phase - reaching agreement    | Renamed `consensus.establish`                                    | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.phase.accept`       | Accept phase - applying consensus       | Renamed `consensus.accept`                                       | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.proposal.receive`   | Receive peer proposal                   | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.proposal.send`      | Send our proposal                       | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.validation.receive` | Receive peer validation                 | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `consensus.validation.send`    | Send our validation                     | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `rpc.request`                  | HTTP/WebSocket request handling         | Split into `rpc.http_request` / `rpc.ws_message`                 | —                                                                                                                                                                                                                                                                                                          |
-| `rpc.command.*`                | Specific RPC command (dynamic)          | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `peer.connect`                 | Peer connection establishment           | **Not built**                                                    | **Gap, scoped as its own change** — see [09 §6.4](./09-data-collection-reference.md#64-peer-span-coverage-gap-not-implemented). Adding these changes the 41-family span count and the 40 catalogued in `expected_spans.json`.                                                                              |
-| `peer.disconnect`              | Peer disconnection                      | **Not built**                                                    | **Gap.** Partially observable: the aggregate count via the `Overlay.Peer_Disconnects` insight gauge and resource-charge drops via `server_info{metric="peer_disconnects_resources"}`, but not per-reason. Disconnect reasons are only recoverable from `debug.log` (the `log-derived-insights` dashboard). |
-| `peer.message.send`            | Send protocol message                   | **Not built**                                                    | **Gap.** Of the 13 protocol message families only `mtGET_OBJECTS` has native instrumentation (`getobject_*`); byte/message volume is aggregated by `TrafficCount` category, not traced per message.                                                                                                        |
-| `peer.message.receive`         | Receive protocol message                | **Not built**                                                    | **Gap.** Same as `peer.message.send`.                                                                                                                                                                                                                                                                      |
-| `ledger.acquire`               | Ledger acquisition from network         | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `ledger.build`                 | Build new ledger                        | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `ledger.validate`              | Ledger validation                       | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `ledger.close`                 | Close ledger                            | Renamed `consensus.ledger_close`                                 | —                                                                                                                                                                                                                                                                                                          |
-| `ledger.replay`                | Ledger replay executed                  | **Not built**                                                    | **Gap, no substitute.** `LedgerReplayer.cpp` and `LedgerReplayTask.cpp` contain zero `SpanGuard` uses and no metric covers the replay path. A real hole, not a trade-off.                                                                                                                                  |
-| `ledger.delta`                 | Delta-based ledger acquired             | **Not built**                                                    | **Gap, no substitute.** `LedgerDeltaAcquire.cpp` contains zero `SpanGuard` uses. The `acquire_*` stats cover whole-ledger acquisition, not the delta path.                                                                                                                                                 |
-| `pathfind.request`             | Path request initiated                  | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `pathfind.compute`             | Path computation executed               | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `txq.enqueue`                  | Transaction queued                      | Live                                                             | —                                                                                                                                                                                                                                                                                                          |
-| `txq.apply`                    | Queued transaction applied              | Renamed `txq.apply_direct` / `txq.accept_tx`                     | —                                                                                                                                                                                                                                                                                                          |
-| `fee.escalate`                 | Fee escalation triggered                | **Not built**                                                    | **Superseded by metrics + existing spans.** Escalation state is `txq_metrics{metric=…}` and `load_factor_metrics{metric=…}`; the queueing path that triggers it is already traced by the six `txq.*` spans. An event span would restate a gauge.                                                           |
-| `validator.list.fetch`         | UNL list fetched                        | **Not built**                                                    | **Superseded by metrics.** `validator_health{metric="unl_expiry_days"}`, `{metric="unl_blocked"}` and `{metric="validation_quorum"}` carry the outcome. A fetch span would fire on a slow timer and tell an operator nothing the gauges do not.                                                            |
-| `validator.manifest`           | Manifest update processed               | **Not built**                                                    | **Superseded by logs.** Per-master-key manifest dispositions are on the `log-derived-insights` dashboard (`ManifestCache` partition, requires `log_level ManifestCache debug`).                                                                                                                            |
-| `amendment.vote`               | Amendment voting executed               | **Not built**                                                    | **Deferred to Phase 11.** `validator_health{metric="amendment_blocked"}` covers the blocked state in the meantime.                                                                                                                                                                                         |
-| `shamap.sync`                  | State tree synchronization              | **Not built**                                                    | **Superseded by metrics.** Covered by the nine `acquire_*` stats, `nodestore_state{metric=…}` and the five `getobject_*` families. Per-node-fetch spans would be prohibitive volume.                                                                                                                       |
-| `job.enqueue`                  | Job added to queue                      | **Not built**                                                    | **Superseded by metrics.** `job_queued_total` and `job_queued_us{job_type}` plus the 105 per-job-type `jobq_*` gauges. A span per enqueue is one span per unit of daemon work, for latency the histogram already records exactly.                                                                          |
-| `job.execute`                  | Job execution                           | **Not built**                                                    | **Superseded by metrics.** `job_started_total`, `job_finished_total`, `job_running_us{job_type}`. Same volume argument as `job.enqueue`.                                                                                                                                                                   |
-
-### 2.3.3 Attribute Naming Conventions
-
-Span **names** follow §2.3.1 (dotted `<component>.<operation>`). Span
-**attribute keys** follow the rules below. The constants in the `*SpanNames.h`
-headers are the single source of truth; the collector, Tempo, the Grafana
-dashboards, and the runbook all consume these exact keys, so every layer must
-agree with the code. A CI check enforces this end to end.
-
-1. **Per-span unique attribute** → bare field name, allowed when the field is
-   recorded by a single span/workflow so the span name already supplies the
-   domain (e.g. `command`, `version`, `local` on `rpc.command`).
-2. **Shared attribute (same concept on more than one span)** → ONE key, reused
-   verbatim on every span that records it; the span name tells the occurrences
-   apart, so no per-emitter prefix is added. Name it by the field's meaning: a
-   property of a domain object keeps that object's bare field name (`ledger_hash`,
-   `ledger_seq`, `tx_hash`, `peer_id`, `full_validation`); a field already
-   qualified by a sub-kind keeps that qualifier on every emitter (`proposal_trusted`
-   on both `consensus.proposal.receive` and `peer.proposal.receive`;
-   `validation_trusted` likewise). Defined once in the base `SpanNames.h`
-   `namespace attr` block and re-exported (`using`) by each domain header.
-3. **Collision qualifier** → `<domain>_<field>`, only when a bare name would
-   collide with a DIFFERENT concept in the shared spanmetrics label space or with
-   the OTel-reserved `status` key (e.g. `rpc_status`, `grpc_status`,
-   `consensus_phase`, `consensus_round`, `consensus_mode`). This disambiguates
-   distinct concepts that share a word; it is NOT used to tag the same concept
-   with its emitting workflow — that is rule 2 (one shared name).
-4. **Resource attribute** → dotted `xrpl.<subsystem>.<field>`, reserved ONLY
-   for process/network identity set once at startup (`xrpl.network.id`,
-   `xrpl.network.type`). Span attributes are never dotted in the `xrpl.` form —
-   it blurs the resource/span scope boundary and parses awkwardly in TraceQL.
-5. **Span names** use `<subsystem>[.<component>]` (dotted, per §2.3.1). Only
-   attribute _keys_ follow rules 1–4.
-
-Standard OpenTelemetry semantic-convention keys keep their canonical dotted
-form (e.g. `service.*` resource attributes, `http.*` span attributes); the
-"no dotted form" rule applies to xrpl-custom keys only.
-
-The same rules are recorded in `CONTRIBUTING.md` (the permanent home, since
-`OpenTelemetryPlan/` is removed once the rollout completes). The attribute
-examples in §2.4 below follow these rules.
-
----
-
-## 2.4 Attribute Schema
-
-> **TxQ** = Transaction Queue | **UNL** = Unique Node List | **OTLP** = OpenTelemetry Protocol
-
-### 2.4.1 Resource Attributes (Set Once at Startup)
-
-Resource attributes identify the process and are set once at startup. They use
-the standard OpenTelemetry semantic conventions plus custom dotted `xrpl.*`
-keys (the dotted form is reserved for resource scope per §2.3.3).
-
-Five are set, by `Telemetry.cpp:380-387` (tracer resource) and the matching
-block in `initMetrics()` (metrics resource); the custom key constants are
-`SpanNames.h:117-118`.
-
-| Key                   | Type / value                                                   | Description                    | Status                                                                                                                                                                                                                                                                                          |
-| --------------------- | -------------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `service.name`        | `"xrpld"`                                                      | Standard `SERVICE_NAME`        | Set                                                                                                                                                                                                                                                                                             |
-| `service.version`     | `build_info::getVersionString()`                               | Standard `SERVICE_VERSION`     | Set                                                                                                                                                                                                                                                                                             |
-| `service.instance.id` | node public key (base58), or `[telemetry] service_instance_id` | Standard `SERVICE_INSTANCE_ID` | Set — but the node-key fallback reaches traces only; see [05 §5.1.1](./05-configuration-reference.md)                                                                                                                                                                                           |
-| `xrpl.network.id`     | network id (e.g. 0 for mainnet)                                | Network identifier             | Set                                                                                                                                                                                                                                                                                             |
-| `xrpl.network.type`   | `"mainnet"` \| `"testnet"` \| `"devnet"` \| `"unknown"`        | Network kind                   | Set                                                                                                                                                                                                                                                                                             |
-| `xrpl.node.type`      | `"validator"` \| `"stock"` \| `"reporting"`                    | Node role                      | **Not implemented** — no constant, no set-site. Node role is therefore not queryable from a trace. (Dashboards do offer an `$xrpl_node_role` filter, but it matches a Prometheus label stamped by the external perf-iac deployment — `check_otel_naming.py:872` — not by anything in this repo) |
-| `xrpl.node.cluster`   | cluster name                                                   | Cluster name, if clustered     | **Not implemented** — no constant, no set-site                                                                                                                                                                                                                                                  |
-
-The collector adds two more resource attributes of its own (`deployment.environment`
-and, when the node did not stamp it, `xrpl.network.type`) via the
-`resource/tier` processor, and deletes the SDK-injected `telemetry.sdk.*` trio
-via `resource/stripsdk`. See [05 §5.5.1](./05-configuration-reference.md).
-
-### 2.4.2 Span Attributes by Category
-
-> Span attribute keys use the underscore form from §2.3.3 (shared/qualified
-> keys are `<domain>_<field>`; per-span unique keys are bare). The dotted form
-> is reserved for the resource attributes in §2.4.1 above. This catalog lists
-> the planned attribute set by category; the exact emitted key **and its type**
-> for each implemented span is defined by the `*SpanNames.h` constants and their
-> set-sites, which win where the two differ. The types in the tables below are
-> the ones originally planned and are **not** all what shipped — `peer_id` is
-> the notable case (planned as a base58 string, shipped as an int64). §2.4.3
-> is the implemented view.
-
-#### Transaction Attributes
-
-| Key            | Type   | Description                           |
-| -------------- | ------ | ------------------------------------- |
-| `tx_hash`      | string | Transaction hash (hex)                |
-| `tx_type`      | string | `"Payment"`, `"OfferCreate"`, etc.    |
-| `tx_account`   | string | Source account (redacted in prod)     |
-| `tx_sequence`  | int64  | Account sequence number               |
-| `tx_fee`       | int64  | Fee in drops                          |
-| `tx_result`    | string | `"tesSUCCESS"`, `"tecPATH_DRY"`, etc. |
-| `ledger_index` | int64  | Ledger containing transaction         |
-| `relay_count`  | int64  | Peers the transaction was relayed to  |
-| `suppressed`   | bool   | `true` when HashRouter dropped a dup  |
-
-#### Consensus Attributes
-
-| Key                  | Type    | Description                         |
-| -------------------- | ------- | ----------------------------------- |
-| `consensus_round`    | int64   | Round number                        |
-| `consensus_phase`    | string  | `"open"`, `"establish"`, `"accept"` |
-| `consensus_mode`     | string  | `"proposing"`, `"observing"`, etc.  |
-| `proposers`          | int64   | Number of proposers                 |
-| `prev_ledger_prefix` | string  | Previous ledger hash prefix         |
-| `ledger_seq`         | int64   | Ledger sequence                     |
-| `tx_count`           | int64   | Transactions in consensus set       |
-| `round_time_ms`      | float64 | Round duration                      |
-
-Establish-phase gap fill and cross-node correlation attributes (Phase 4a):
-
-| Key                   | Type   | Description                                               |
-| --------------------- | ------ | --------------------------------------------------------- |
-| `consensus_round_id`  | int64  | Consensus round number                                    |
-| `consensus_ledger_id` | string | `previousLedger.id()` — shared across nodes               |
-| `trace_strategy`      | string | `"deterministic"` or `"attribute"`                        |
-| `converge_percent`    | int64  | Convergence % (0-100+)                                    |
-| `establish_count`     | int64  | Number of establish iterations                            |
-| `disputes_count`      | int64  | Active disputed transactions                              |
-| `agree_count`         | int64  | Peers that agree (haveConsensus)                          |
-| `disagree_count`      | int64  | Peers that disagree                                       |
-| `threshold_percent`   | int64  | Close-time consensus threshold (`avCT_CONSENSUS_PCT`=75%) |
-| `consensus_result`    | string | `"yes"`, `"no"`, `"moved_on"`, `"expired"`                |
-| `mode_old`            | string | Previous consensus mode                                   |
-| `mode_new`            | string | New consensus mode                                        |
-
-#### RPC Attributes
-
-| Key           | Type    | Description                                                                   |
-| ------------- | ------- | ----------------------------------------------------------------------------- |
-| `command`     | string  | Command name (per-span unique on `rpc.command`)                               |
-| `version`     | int64   | API version                                                                   |
-| `rpc_role`    | string  | `"admin"` or `"user"` (qualified — `role` is generic)                         |
-| `params`      | string  | Sanitized parameters (optional)                                               |
-| `rpc_status`  | string  | Response status: `success` \| `error` (qualified — `status` is OTel-reserved) |
-| `duration_ms` | float64 | Request duration in milliseconds                                              |
-
-#### Peer & Message Attributes
-
-| Key                  | Type    | Description                                                               |
-| -------------------- | ------- | ------------------------------------------------------------------------- |
-| `peer_id`            | string  | Peer public key (base58) — **planned only; shipped as int64, see §2.4.3** |
-| `peer_address`       | string  | IP:port                                                                   |
-| `peer_latency_ms`    | float64 | Measured latency                                                          |
-| `peer_cluster`       | string  | Cluster name if clustered                                                 |
-| `message_type`       | string  | Protocol message type name                                                |
-| `message_size_bytes` | int64   | Message size                                                              |
-| `message_compressed` | bool    | Whether compressed                                                        |
-
-#### Ledger & Job Attributes
-
-| Key               | Type    | Description           |
-| ----------------- | ------- | --------------------- |
-| `ledger_hash`     | string  | Ledger hash           |
-| `ledger_index`    | int64   | Ledger sequence/index |
-| `close_time`      | int64   | Close time (epoch)    |
-| `ledger_tx_count` | int64   | Transaction count     |
-| `job_type`        | string  | Job type name         |
-| `job_queue_ms`    | float64 | Time spent in queue   |
-| `job_worker`      | int64   | Worker thread ID      |
-
-#### PathFinding Attributes
-
-| Key                        | Type   | Description               |
-| -------------------------- | ------ | ------------------------- |
-| `pathfind_source_currency` | string | Source currency code      |
-| `pathfind_dest_currency`   | string | Destination currency code |
-| `pathfind_path_count`      | int64  | Number of paths found     |
-| `pathfind_cache_hit`       | bool   | RippleLineCache hit       |
-
-#### TxQ Attributes
-
-| Key                   | Type   | Description                 |
-| --------------------- | ------ | --------------------------- |
-| `txq_queue_depth`     | int64  | Current queue depth         |
-| `txq_fee_level`       | int64  | Fee level of transaction    |
-| `txq_eviction_reason` | string | Why transaction was evicted |
-
-#### Fee Attributes
-
-| Key                    | Type  | Description               |
-| ---------------------- | ----- | ------------------------- |
-| `fee_load_factor`      | int64 | Current load factor       |
-| `fee_escalation_level` | int64 | Fee escalation multiplier |
-
-#### Validator Attributes
-
-| Key                      | Type  | Description               |
-| ------------------------ | ----- | ------------------------- |
-| `validator_list_size`    | int64 | UNL size                  |
-| `validator_list_age_sec` | int64 | Seconds since last update |
-
-#### Amendment Attributes
-
-| Key                | Type   | Description                            |
-| ------------------ | ------ | -------------------------------------- |
-| `amendment_name`   | string | Amendment name                         |
-| `amendment_status` | string | `"enabled"`, `"vetoed"`, `"supported"` |
-
-#### SHAMap Attributes
-
-| Key                    | Type    | Description                                   |
-| ---------------------- | ------- | --------------------------------------------- |
-| `shamap_type`          | string  | `"transaction"`, `"state"`, `"account_state"` |
-| `shamap_missing_nodes` | int64   | Number of missing nodes during sync           |
-| `shamap_duration_ms`   | float64 | Sync duration                                 |
-
-### 2.4.3 Data Collection Summary
-
-§2.4.2 above is the _planned_ catalogue; this table is the **implemented** one.
-Its left column lists the keys of the `attr` namespaces of the `*SpanNames.h`
-headers; every key shown has at least one live `attr::` set-site in
-non-test code. The right column lists keys this document once claimed were
-collected but which have no constant and no set-site at all.
-
-**This table is a category-level roll-up, not the authority.** The
-authoritative per-span breakdown — which span carries which attribute — is
-[09-data-collection-reference.md §1.2](./09-data-collection-reference.md#12-complete-attribute-inventory-bareunderscore-keys),
-and the exact key _spelling_ is owned by the `*SpanNames.h` constants. Where
-this table disagrees with either, they win.
-
-> **Known divergence (documented, not resolved here).** 09 §1.2's Consensus
-> subsection lists 47 keys; `include/xrpl/consensus/ConsensusSpanNames.h`
-> defines 54 in its `attr` namespace (48 own `makeStr` constants plus 6
-> `using` re-exports of the shared keys in `SpanNames.h`), all 54 with
-> set-sites. Five of the difference — `open_duration_ms`,
-> `peer_positions_at_close`, `position_hash_prefix`, `prev_ledger_prefix`,
-> `disputes_resolved_count` — are emitted but absent from 09 §1.2's consensus
-> table; the other two, `proposal_trusted` and `validation_trusted`, are
-> documented in 09 §1.2's Peer subsection instead (they are shared keys set on
-> both the `peer.*` and the `consensus.*` receive spans — `PeerImp.cpp:1953`
-> and `:2027` for the proposal pair, `:2591` and `:2635` for the validation
-> pair). Fixing 09 is tracked separately; the Consensus row below lists all 54.
-
-| Category        | Attributes emitted (from `*SpanNames.h`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Named here but NOT emitted                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Purpose                      |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
-| **Transaction** | `tx_hash`, `tx_type`, `ter_result`, `fee`, `sequence`, `current_ledger_seq`, `current_ledger_hash`, `local`, `path`, `suppressed`, `tx_status`, `peer_version`, `peer_id`, `stage`, `applied`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `tx_result` (renamed → `ter_result`), `tx_fee` (→ `fee`), `ledger_index` (→ `current_ledger_seq`), `relay_count`. **`ledger_seq` is not a `tx.*` key**: no `tx.*` span sets it — the receive and apply-stage spans stamp `current_ledger_seq` (`NetworkOPs.cpp:1422`, `PeerImp.cpp:1337`, `Transactor.cpp:1613`, `applySteps.cpp:115`) and, where a view exists, `current_ledger_hash` (`Transactor.cpp:1615`, `applySteps.cpp:121`)                                                                                                                                                                                      | Trace transaction lifecycle  |
-| **Consensus**   | All 54 keys in `ConsensusSpanNames.h`'s `attr` namespace (48 own constants + 6 `using` re-exports), each with a set-site: `consensus_ledger_id`, `consensus_round`, `consensus_round_id`, `consensus_phase`, `consensus_mode`, `consensus_state`, `consensus_result`, `consensus_stalled`, `proposers`, `proposers_finished`, `previous_proposers`, `previous_ledger_seq`, `previous_round_time_ms`, `round_time_ms`, `open_duration_ms`, `quorum`, `proposing`, `is_bow_out`, `trace_strategy`, `converge_percent`, `establish_count`, `tx_count`, `tx_count_open`, `tx_id`, `disputes_count`, `disputes_resolved_count`, `dispute_our_vote`, `dispute_yays`, `dispute_nays`, `agree_count`, `disagree_count`, `threshold_percent`, `avalanche_threshold`, `close_time_threshold`, `have_close_time_consensus`, `close_time_resolution_ms`, `close_time_self`, `close_time_vote_bins`, `resolution_direction`, `parent_close_time`, `peer_positions_at_close`, `prev_ledger_prefix`, `position_hash_prefix`, `mode_old`, `mode_new`, `validation_sign_time`, `proposal_trusted`, `validation_trusted`; re-exported shared keys `ledger_seq`, `ledger_hash`, `full_validation`, `close_time`, `close_time_correct`, `close_resolution_ms` | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Analyze consensus timing     |
-| **RPC**         | `command`, `version`, `rpc_role`, `rpc_status`, `request_payload_size`, `is_batch`, `batch_size`, `load_type`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `duration_ms` (span duration is a TraceQL intrinsic — query `duration`), `params`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Monitor RPC performance      |
-| **Peer**        | `peer_id` (**int64**, the process-local `Peer::id_` slot number — not a key of any kind; also set on `tx.receive`), `proposal_trusted`, `validation_trusted`, `ledger_hash`, `full_validation`. (`peer_version` is **not** a peer-span key: the constant lives in `TxSpanNames.h:79` and its only set-site is `PeerImp.cpp:1342` on the `tx.receive` span — see the Transaction row)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `peer_address`, `peer_latency_ms`, `peer_cluster`, `message_type`, `message_size_bytes`, `message_compressed` — the peer-span coverage gap (§2.3.2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Network topology analysis    |
-| **Ledger**      | `ledger_seq`, `tx_count`, `tx_failed`, `validations`, `acquire_reason`, `timeouts`, `peer_count`, `outcome`, `close_time`, `close_time_correct`, `close_resolution_ms`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `ledger_index` (→ `ledger_seq`), `ledger_tx_count` (→ `tx_count`). `ledger_hash` is a live key, but **no `ledger.*` span sets it** — only `consensus.validation.send` (`RCLConsensus.cpp:977`; that span is the one returned by `createValidationSpan()`, which names `cs::validationSend` at `RCLConsensus.cpp:1365,1373`) and `peer.validation.receive` (`PeerImp.cpp:2573`) do. The `LedgerSpanNames.h:41` `using` alias has zero uses. `consensus.ledger_close` sets **no** hash: its four attributes are `ledger_seq`, `consensus_mode`, `tx_count_open` and `close_time_resolution_ms` (`RCLConsensus.cpp:354-361`) | Ledger progression tracking  |
-| **gRPC**        | `method`, `grpc_role`, `grpc_status`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | gRPC surface monitoring      |
-| **Job**         | — (no job spans exist)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `job_type`, `job_queue_ms`, `job_worker`. JobQueue is observed via **metrics**, not spans — but by **two disjoint families**, and only one of them has a `job_type` label. See the note below the table                                                                                                                                                                                                                                                                                                                                                                                                                   | JobQueue performance         |
-| **PathFinding** | `pathfind_fast`, `pathfind_search_level`, `pathfind_num_paths`, `pathfind_ledger_index`, `pathfind_num_requests`, `pathfind_num_source_assets`, `pathfind_dest_currency`, `pathfind_source_account` (hashed), `pathfind_dest_account` (hashed)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `pathfind_source_currency`, `pathfind_path_count`, `pathfind_cache_hit`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Payment path analysis        |
-| **TxQ**         | `txq_status`, `fee_level_paid`, `required_fee_level`, `queue_size`, `ledger_changed`, `expired_count`, `ter_code`, `retries_remaining`, `num_cleared`, `tx_type`, plus the re-exported shared keys `tx_hash`, `ledger_seq`, `current_ledger_seq`, `current_ledger_hash`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `txq_queue_depth` (→ `queue_size`), `txq_fee_level` (→ `fee_level_paid`), `txq_eviction_reason`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Queue depth and fee tracking |
-| **Fee**         | — (no `fee.escalate` span, §2.3.2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `fee_load_factor`, `fee_escalation_level`. Fee escalation is dashboarded from metrics (`fee-market`), not spans                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Fee escalation monitoring    |
-| **Validator**   | — (no `validator.*` span, §2.3.2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `validator_list_size`, `validator_list_age_sec`. UNL health is dashboarded from metrics (`validator-health`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | UNL health monitoring        |
-| **Amendment**   | — (no `amendment.vote` span, §2.3.2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `amendment_name`, `amendment_status`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Protocol upgrade tracking    |
-| **SHAMap**      | — (no `shamap.sync` span, §2.3.2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `shamap_type`, `shamap_missing_nodes`, `shamap_duration_ms`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | State tree sync performance  |
-
-The right-hand column is the honest gap list: every key in it appears in the
-§2.4.2 design catalogue but has **zero set-sites** in the code. Where a rename
-happened the live name is given in parentheses; where the concept shipped as a
-metric rather than a span that is stated. Do not build a dashboard panel, an
-alert rule, or a TraceQL query against anything in that column — the query will
-return empty, and (per the PromQL/TraceQL asymmetry) a `=~".*"` matcher on an
-absent attribute silently blanks a TraceQL panel while quietly passing in
-PromQL.
-
-> **JobQueue metrics: two families, one label.** The Job row above has no span
-> attributes, and the metrics that replace them do **not** all carry a
-> `job_type` label. Getting this wrong produces a panel that renders but is
-> wrong, so treat the two families as separate query surfaces:
->
-> | Family                                                                                                                   | Where the job type lives                                                | Source                                                                                      |
-> | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-> | Native `XRPL_METRIC_*`: `job_queued_total`, `job_started_total`, `job_finished_total`, `job_queued_us`, `job_running_us` | In a **`job_type` label**                                               | `MetricsRegistry.cpp:360-362` (counters), `:94-95` (histogram names), `:101` (label key)    |
-> | `beast::insight` `jobq` group: `jobq_<jobtype>_waiting` / `_running` / `_deferred` / `_q`                                | In the **metric name itself** — there is **no** `job_type` label at all | `JobTypeData.h:29-32` (naming contract), `:35-38` (suffixes), `Application.cpp:392` (group) |
->
-> **The trap:** `sum by (job_type)(jobq_…)` collapses every job type into a
-> single series with an empty `job_type`, because an absent PromQL label is
-> equivalent to `""` — the query returns a plausible-looking number rather than
-> an error. Aggregate the `jobq_*` family with a name matcher
-> (`{__name__=~"jobq_.*_waiting"}`) and reserve `by (job_type)` for the
-> `job_*_total` / `job_*_us` family.
-
-### 2.4.4 Privacy & Sensitive Data Policy
-
-> **PII** = Personally Identifiable Information
-
-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**        | **Never in spans** — no span sets an address attribute (`peer_address` has zero set-sites); peer spans identify peers by `peer_id`, an int64 process-local slot number. **But the log pipeline is a different story** — see the note below this table |
-
-> **Peer IPs DO leave the node — via the log pipeline, not via spans.** The
-> "IP Addresses" row above is scoped to spans, and only to spans. This same
-> document describes a log pipeline (§2.6.5) that carries peer addresses:
->
-> 1. `PeerImp`'s constructor logs the peer's `remoteAddress_` — an `IP:port` —
->    at `info` severity (`PeerImp.h:837-842`), and other overlay call sites log
->    addresses too. These land in the ordinary `debug.log` stream.
-> 2. The collector's `filelog` receiver tails exactly that file
->    (`otel-collector-config.yaml:38-47`, `include: [/var/log/xrpld/*/debug.log]`)
->    and the `logs` pipeline exports it to Loki (`:236-239`).
->
-> So a deployment running the shipped stack **does** ship peer IPs off-box, as
-> log bodies. There is no attribute to drop and no span-level switch to flip,
-> because the IPs are inside free-text log messages rather than in structured
-> fields — a `delete` action on an attribute key would not touch them.
->
-> **The control points are therefore log-side, not trace-side:** Loki
-> retention and access control on the log store; the `filelog` receiver's
-> `include` list (dropping it disables log↔trace correlation entirely); or a
-> collector-side transform on the log body. Do not describe the telemetry
-> pipeline as IP-free without qualifying it to traces.
-
-#### Privacy Protection Mechanisms
-
-| Mechanism                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Account Hashing**           | Account addresses are hashed both SDK-side (`pathfind_source_account`, `pathfind_dest_account` — always hashed before emission) and again at the collector level, so raw addresses never reach storage                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| **Unconditional Redaction**   | Account redaction is **not** configurable and cannot be turned off: `redactAccount()` (`Redaction.cpp:14-29`) hashes every **non-empty** address handed to it, with no flag and no bypass (an empty input returns empty — `Redaction.cpp:18-19` — so there is no raw value to leak either way). That is a stronger guarantee than a config switch: there is no insecure-by-default state to misconfigure                                                                                                                                                                                                                         |
-| **Collector Tail Sampling**   | **Optional, and OFF in the base stack.** xrpld head sampling is fixed at 1.0 (`Telemetry.h:234` `static constexpr double samplingRatio = 1.0;`), so 100% of traces leave the node. `docker/telemetry/otel-collector-config.yaml` has **no** `tail_sampling` processor either, so the local stack stores 100%. The only shipped policy is in the Grafana Cloud overlay (`otel-collector-config.grafanacloud.yaml:60-67`, wired at `:261`): one `probabilistic` policy at **0.5%**, on the trace-storage branch only so spanmetrics still see every span. Treat sampling as a cost control you opt into — not as a privacy control |
-| **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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-
-#### Account Address Hashing
-
-Account addresses are **always** hashed before they reach the telemetry
-backend — there is no opt-out flag and therefore no insecure-by-default
-failure mode. Protection is applied in two independent layers:
-
-1. **SDK-side** (this node): the path-finding RPC handlers call
-   `redactAccount()` (`xrpl::telemetry`, `Redaction.h`) before setting the
-   `pathfind_source_account` / `pathfind_dest_account` span attributes. For a
-   non-empty address the helper emits the first 16 characters of
-   `sha512Half(address)` as lowercase hex — deterministic (spans for one
-   account still correlate) but non-reversible. An empty address returns empty
-   rather than the hash of the empty string (`Redaction.cpp:18-19`).
-2. **Collector-side** (defense-in-depth): an `attributes/hash` processor in
-   the OpenTelemetry Collector re-hashes those same attributes, so any node
-   that emitted a raw value is still redacted before storage.
-
-#### Collector-Level Data Protection
-
-The shipped base config does exactly one thing here, and it is the
-defense-in-depth layer described above: an `attributes/hash` processor
-(`otel-collector-config.yaml:105-110`) hashing `pathfind_source_account` and
-`pathfind_dest_account`.
-
-**No `peer_address` or `params` scrubbing rule is needed on the trace pipeline,
-and none is shipped.** Earlier drafts prescribed `delete` actions for both.
-Neither attribute is ever emitted: `peer_address` has zero set-sites in the code
-(peer spans carry `peer_id`, an int64 process-local slot number — not an IP and
-not a key), and no span sets a `params` attribute — RPC spans carry `command`,
-`version`, `rpc_role`, `rpc_status`, `request_payload_size`, `is_batch`,
-`batch_size` and `load_type`, never the request body. Adding delete rules for
-absent keys would be harmless but misleading: it would imply the node emits IPs
-and request parameters in spans when it does not.
-
-This says nothing about the **log** pipeline, which is where peer IPs actually
-do leave the node (see the note under "Data NOT Collected" above). An
-`attributes` processor cannot help there — the addresses are inside free-text
-log bodies, not in structured attributes.
-
-If a future span _does_ introduce an IP-bearing or payload-bearing attribute,
-the `attributes` processor is the right place to strip it — and the attribute
-should be added to the §2.4 catalogue in the same change.
-
-#### Configuration Options for Privacy
-
-In `xrpld.cfg`, operators control data collection granularity through the
-`[telemetry]` section. Besides `enabled`, per-component toggles
-(`trace_transactions`, `trace_consensus`, `trace_rpc`, `trace_peer` — the last
-often disabled due to high volume) select which spans are emitted. Account
-address hashing is not configurable: addresses are hashed unconditionally by
-the SDK helper described above, with collector-level hashing as a second
-layer.
-
-> **Key Principle**: Telemetry collects **operational metadata** (timing, counts, hashes) — never **sensitive content** (keys, balances, amounts, raw payloads).
-
-> **See also**: [Securing the OTel Pipeline](./secure-OTel.md) covers transport-level protection for telemetry leaving the node — mTLS to the collector and validation of incoming peer trace context. Privacy controls in this section keep sensitive data out of spans; the security doc keeps the spans themselves out of untrusted hands.
-
----
-
-## 2.5 Context Propagation Design
-
-> **WS** = WebSocket
-
-### 2.5.0 Deterministic Trace ID Strategy
-
-Both transaction and consensus tracing use **deterministic trace IDs** derived from
-a globally known hash, so all nodes handling the same workflow independently produce
-spans under the same `trace_id`. This is combined with protobuf `span_id` propagation
-for parent-child relay ordering when available.
-
-#### Transactions — `trace_id = txHash[0:16]`
-
-Every node that handles a transaction knows its `txID` (the `uint256` transaction
-hash). The first 16 bytes of this hash are used as the OTel `trace_id`:
-
-```
-uint256 txHash:  A1B2C3D4 E5F6A7B8 C9D0E1F2 A3B4C5D6  E7F8A9B0 C1D2E3F4 A5B6C7D8 E9F0A1B2
-                 |---------- trace_id (16 bytes) ---------|  (remaining 16 bytes unused)
-```
-
-Each node generates a **random 8-byte `span_id`** so its span is unique within the
-shared trace. When protobuf `TraceContext` is present in the incoming `TMTransaction`,
-the sender's `span_id` is extracted and used as the parent — preserving the relay
-chain as a parent-child tree. When absent (older peers, first hop from client), the
-span appears as a root in the same trace — correlation is preserved, only the tree
-structure degrades.
-
-```
-Node A (submitter)        Node B (relay)          Node C (relay)
-trace_id: A1B2...         trace_id: A1B2...       trace_id: A1B2...
-span_id:  1234 (random)   span_id:  5678 (random) span_id:  9ABC (random)
-parent:   (none)          parent:   1234 (proto)   parent:   5678 (proto)
-                               ↑                        ↑
-                       protobuf propagation      protobuf propagation
-```
-
-If protobuf propagation fails at Node B (old peer):
-
-```
-Node A                    Node B (old peer)       Node C
-trace_id: A1B2...         trace_id: A1B2...       trace_id: A1B2...
-span_id:  1234            span_id:  5678          span_id:  9ABC
-parent:   (none)          parent:   (none)        parent:   5678 (proto)
-                          ↑ no parent, but same trace_id — still grouped
-```
-
-#### Consensus — `trace_id = prevLedgerHash[0:16]`
-
-All validators in the same consensus round share the same `previousLedger.id()`.
-The first 16 bytes are used as trace_id. See [Phase 4a implementation status](./06-implementation-phases.md)
-and `createDeterministicContext()` in `RCLConsensus.cpp` for the implementation.
-
-Switchable via `consensus_trace_strategy` config:
-`"deterministic"` (default) or `"attribute"` (random trace_id, correlation via attribute queries).
-
-#### Why Not Random IDs with Propagation Only?
-
-Random trace IDs require **unbroken context propagation** across every hop. In a
-mixed-version network (common during upgrades), older peers silently drop the
-`trace_context` protobuf field. The trace splits and downstream spans become
-impossible to find. Deterministic IDs make correlation **propagation-resilient** — the trace
-backend groups all spans for the same transaction/round regardless of whether
-propagation succeeded.
-
-#### Why Keep Protobuf Propagation?
-
-Deterministic trace IDs alone provide correlation (all spans grouped) but not
-**causality** (which node relayed to which). Protobuf `span_id` propagation adds
-parent-child ordering that shows the exact relay path. The two mechanisms complement
-each other:
-
-| Mechanism                    | Provides                    | Fails when                             |
-| ---------------------------- | --------------------------- | -------------------------------------- |
-| Deterministic trace_id       | Cross-node correlation      | Never (hash is always known)           |
-| Protobuf span_id propagation | Parent-child relay ordering | Older peer drops `trace_context` field |
-
-#### Implementation Reference
-
-The utility function `createDeterministicTxContext(uint256 const& txHash)` follows
-the same pattern as `createDeterministicContext(uint256 const& ledgerId)` in
-`RCLConsensus.cpp`. See [Phase 3 Task 3.9](./Phase3_taskList.md) for the full spec.
-
-### 2.5.1 Propagation Boundaries
-
-```mermaid
-flowchart TB
-    subgraph http["HTTP/WebSocket (RPC)"]
-        w3c["W3C Trace Context Headers:<br/>traceparent:<br/>00-trace_id-span_id-flags<br/>tracestate: xrpld=..."]
-    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 / Coroutines (Internal Async)"]
-        job["CoroAwareContextStorage<br/>(RuntimeContextStorage override)<br/><br/>Per-coroutine context stack,<br/>installed globally at startup.<br/>Job itself carries no context."]
-    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
-```
-
-**Reading the diagram:**
-
-- **HTTP/WebSocket - RPC (blue)**: For client-facing RPC requests, trace context is propagated using the W3C `traceparent` header. This is the standard approach and works with any OTel-compatible client.
-- **Protocol Buffers - P2P (green)**: For peer-to-peer messages between xrpld nodes, trace context is embedded as a protobuf `TraceContext` message carrying trace_id, span_id, flags, and optional trace_state.
-- **JobQueue / Coroutines - Internal Async (red)**: For asynchronous work within a single node, the ambient OTel context follows the coroutine rather than being carried on the work item. `include/xrpl/core/Job.h` has **no** telemetry include and no `traceContext_` member — an earlier draft of this diagram showed one, and that was never built. Instead `xrpl::telemetry::CoroAwareContextStorage` (`include/xrpl/telemetry/CoroAwareContextStorage.h:84`) overrides the SDK's `RuntimeContextStorage` with a per-coroutine context stack, and is installed as the global storage in `Telemetry::start()` (`Telemetry.cpp:416-419`) before the tracer provider and before the first span. That fixes the wrong-thread scope pop across coroutine yield/resume and keeps log↔trace correlation intact. The storage is never reset — tearing it down while spans may still exist is undefined behaviour in the SDK — so it lives for the process lifetime.
-
----
-
-## 2.6 Integration with Existing Observability
-
-> **OTLP** = OpenTelemetry Protocol | **WS** = WebSocket
-
-### 2.6.1 Existing Frameworks Comparison
-
-xrpld 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
-
-A PerfLog entry is a JSON object with fields such as `time`, `method`,
-`duration_us`, and `result`.
-
-#### 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
-
-In xrpld, Beast Insight is used through `increment` (counters), `gauge`
-(point-in-time values), and `timing` (durations) calls.
-
-#### 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
-
-A span is created via `startSpan` (e.g. `"tx.relay"`), annotated with
-attributes such as `tx_hash` and `peer_id`, and is automatically linked to its
-parent through the active context.
-
-### 2.6.3 When to Use Each
-
-| Scenario                                | PerfLog    | StatsD | OpenTelemetry |
-| --------------------------------------- | ---------- | ------ | ------------- |
-| "How many TXs per second?"              | ❌         | ✅     | ✅            |
-| "What's the p99 RPC latency?"           | ❌         | ✅     | ✅            |
-| "Why was this specific TX slow?"        | ⚠️ partial | ❌     | ✅            |
-| "Which node delayed consensus?"         | ❌         | ❌     | ✅            |
-| "What happened on node X at time T?"    | ✅         | ❌     | ✅            |
-| "Show me the TX journey across 5 nodes" | ❌         | ❌     | ✅            |
-
-### 2.6.4 Coexistence Strategy
-
-> **Note**: Phase 7 **added** a native OTel Metrics export path alongside the
-> StatsD bridge; it did not replace it. The diagram below shows the Phase 6
-> state, which is still reachable today via `[insight] server=statsd`. See
-> [Phase7_taskList.md](./Phase7_taskList.md) for the design.
-
-```mermaid
-flowchart TB
-    subgraph xrpld["xrpld 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 xrpld fill:#212121,stroke:#0a0a0a,color:#ffffff
-    style grafana fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **xrpld Process (dark gray)**: The single xrpld node running all three observability frameworks side by side. Each framework operates independently with no interference.
-- **PerfLog to perf.log**: PerfLog writes JSON-formatted event logs to a local file. Grafana can ingest these via Loki or a file-based datasource.
-- **Beast Insight to StatsD Server**: Insight sends aggregated metrics (counters, gauges) over UDP to a StatsD server. Grafana reads from StatsD-compatible backends like Graphite or Prometheus (via StatsD exporter).
-- **OpenTelemetry to OTLP Collector**: OTel exports spans over OTLP/HTTP to a Collector, which then forwards to a trace backend (Tempo). (OTLP/gRPC is future work — §2.2.2.)
-- **Grafana (red, unified UI)**: All three data streams converge in Grafana, enabling operators to correlate logs, metrics, and traces in a single dashboard.
-
-**Phase 7 outcome (as shipped)**: Beast Insight gained an `OTelCollector`
-`Collector` implementation that rides the global MeterProvider and exports via
-OTLP/HTTP to the same collector as traces. It is selected with
-`[insight] server=otel`.
-
-The three back ends are **co-equal branches of one `if/else` chain** in
-`makeCollectorManager()` (`CollectorManager.cpp:37-75`), not a migration path:
-
-| `[insight] server=`    | Collector         | Status                                                                                                                                   |
-| ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `otel`                 | `OTelCollector`   | OTLP/HTTP to the OTel Collector — the recommended setting                                                                                |
-| `statsd`               | `StatsDCollector` | Unchanged from before Phase 7. **Not deprecated**: no warning is logged, no removal is scheduled, and the code path is not marked legacy |
-| absent / anything else | `NullCollector`   | **The default.** A node with no `[insight]` section emits no metrics at all                                                              |
-
-Two corrections to earlier drafts, both of which matter operationally: StatsD
-is not a "deprecated fallback", and `otel` is not the default — you must set it
-explicitly. See [06-implementation-phases.md §6.8](./06-implementation-phases.md),
-[Phase7_taskList.md](./Phase7_taskList.md), and
-[05 §5.8.6](./05-configuration-reference.md) for which `[insight]` keys are live
-under `server=otel` (most are inert).
-
-### 2.6.5 Correlation with Logs
-
-**Shipped in Phase 8 — and not the way this section originally planned it.**
-The design here was a `setTraceId` hook on PerfLog, fed from the
-`rpc.command.<method>` span in `RPCHandler.cpp`. That hook was never built:
-`setTraceId` has zero occurrences in **source** — the only hits in the tree are
-in these plan documents, describing the design that was dropped — and PerfLog's
-JSON output carries no trace ID.
-
-What shipped instead is broader and needs no per-call-site wiring: the **journal
-sink** stamps the IDs onto _every_ log line written while a span is active.
-`Logs::format()` (`src/libxrpl/basics/Log.cpp:304-338`, inside
-`#ifdef XRPL_ENABLE_TELEMETRY`) reads the thread-local OTel context, and when
-the active span context is valid it prefixes the message with
-`trace_id=<32 hex> span_id=<16 hex>`. It inspects the context value directly
-rather than calling `GetSpan()`, so the common no-span path costs no heap
-allocation.
-
-Because the IDs land in the ordinary `debug.log` stream, correlation is
-end-to-end without touching PerfLog: the collector's `filelog` receiver parses
-`trace_id`/`span_id` as optional capture groups and ships the lines to Loki, and
-Grafana links both directions (Tempo `tracesToLogs` → Loki, Loki derived fields
-→ Tempo). Details in [05 §5.8.5](./05-configuration-reference.md).
-
-RPC spans still exist and still set status (OK on success, error with the
-recorded exception on failure) — that part of the original design is intact.
-Only the PerfLog-stamping mechanism was replaced.
-
----
-
-_Previous: [Architecture Analysis](./01-architecture-analysis.md)_ | _Next: [Implementation Strategy](./03-implementation-strategy.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/03-implementation-strategy.md

@@ -1,545 +0,0 @@
-# Implementation Strategy
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Configuration Reference](./05-configuration-reference.md)
-
----
-
-## 3.1 Directory Structure
-
-The telemetry implementation follows xrpld's existing code organization
-pattern. The tree below is the current on-disk contents of the three telemetry
-directories, and it has three differences from the original design sketch worth
-calling out: `TelemetryConfig.h`, `TraceContext.h`, `SpanAttributes.h` and
-`TraceContext.cpp` were never created (config structs live inside
-`Telemetry.h`, propagation lives in `TraceContextPropagator.h`, and attribute
-constants live in the `*SpanNames.h` headers next to their owning class); the
-metrics work of Phase 7/9 added a whole second module under
-`src/xrpld/telemetry/`, which the sketch predated.
-
-```
-include/xrpl/telemetry/            # libxrpl layer: tracing SDK wrapper
-├── Telemetry.h                    # Interface + Setup config struct + factories
-├── SpanGuard.h                    # RAII span management, factory methods, discard()
-├── SpanNames.h                    # StaticStr/join() + shared span & attr constants
-├── DiscardFlag.h                  # Thread-local discard flag
-├── CoroAwareContextStorage.h      # RuntimeContextStorage override for coroutines
-├── DeterministicIdGenerator.h     # trace_id from txHash / prevLedgerHash
-├── TraceContextPropagator.h       # protobuf TraceContext inject/extract (P2P)
-├── TraceContextValidation.h       # Validation of peer-supplied trace context
-├── Redaction.h                    # redactAccount() — unconditional address hashing
-└── GetObjectMetricNames.h         # getobject_* metric name constants
-
-src/libxrpl/telemetry/
-├── Telemetry.cpp                  # TelemetryImpl + FilteringSpanProcessor + initMetrics()
-├── TelemetryConfig.cpp            # [telemetry] section parsing (makeTelemetrySetup)
-├── SpanGuard.cpp                  # Span/scope guard implementation
-├── CoroAwareContextStorage.cpp
-├── DeterministicIdGenerator.cpp
-├── Redaction.cpp
-└── NullTelemetry.cpp              # No-op impl — ALWAYS compiled (in-source #ifdef)
-
-src/xrpld/telemetry/               # xrpld layer: native metrics + tx tracing helpers
-├── MetricsRegistry.h / .cpp       # Owns the XRPL_METRIC_* instruments + MeterProvider
-├── MetricMacros.h                 # XRPL_METRIC_COUNTER_ADD / _HISTOGRAM_RECORD / ...
-├── ValidationTracker.h            # Validation-agreement tracking (impl in detail/)
-├── detail/ValidationTracker.cpp
-├── ConsensusReceiveTracing.h      # Peer proposal/validation receive spans
-├── PropagationHelpers.h           # Context inject/extract call-site helpers
-├── TxSpanNames.h                  # tx.* span + attribute constants
-└── TxTracing.h                    # Transaction span helpers
-```
-
-Per-class span-name headers deliberately live next to their owning class rather
-than in `telemetry/` — see `ConsensusSpanNames.h`, `TxApplySpanNames.h`,
-`LedgerSpanNames.h`, `RpcSpanNames.h`, `PathFindSpanNames.h`,
-`PeerSpanNames.h`, `TxQSpanNames.h`, `GrpcSpanNames.h`.
-
----
-
-## 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
-
-> **OTLP** = OpenTelemetry Protocol
-
-| Metric        | Overhead   | Notes                                            |
-| ------------- | ---------- | ------------------------------------------------ |
-| CPU           | 1-3%       | Of per-transaction CPU cost (~200μs baseline)    |
-| Memory        | ~10 MB     | SDK statics + batch buffer + worker thread stack |
-| 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
-
-> **Note on hardware assumptions**: The costs below are based on the official OTel C++ SDK CI benchmarks
-> (969 runs on GitHub Actions 2-core shared runners). On production server hardware (3+ GHz Xeon),
-> expect costs at the **lower end** of each range (~30-50% improvement over CI hardware).
-
-| Operation             | Time (ns) | Frequency              | Impact     |
-| --------------------- | --------- | ---------------------- | ---------- |
-| Span creation         | 500-1000  | Every traced operation | Low        |
-| Span end              | 100-200   | Every traced operation | Low        |
-| SetAttribute (string) | 80-120    | 3-5 per span (typical) | Low        |
-| SetAttribute (int)    | 40-60     | 2-3 per span (typical) | Negligible |
-| AddEvent              | 100-200   | 0-2 per span           | Low        |
-| 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-5 attributes per span" is a typical case, not a bound.** The frequency
-> column above describes the median span (`tx.receive`, `rpc.command.*`). A few
-> spans are deliberately attribute-rich: `consensus.accept.apply` sets **13**
-> attributes (`RCLConsensus.cpp:600-674`), and `consensus.round` /
-> `consensus.establish` are of the same order. Use ~15 as the worst case when
-> sizing per-span attribute cost and memory; the consensus spans that hit it fire
-> once per ~3-second round, so their absolute cost stays in the noise
-> (see §3.4.3).
-
-**Source**: Span creation based on OTel C++ SDK `BM_SpanCreation` benchmark (AlwaysOnSampler +
-SimpleSpanProcessor + InMemoryExporter), median ~1,000 ns on CI hardware. AddEvent includes
-timestamp read + string copy + vector push + mutex acquisition. Context injection/extraction
-confirmed by `BM_SpanCreationWithScope` benchmark delta (~160 ns).
-
-### 3.4.2 Transaction Processing Overhead
-
-<div align="center">
-
-```mermaid
-%%{init: {'pie': {'textPosition': 0.75}}}%%
-pie showData
-    "tx.receive (1400ns)" : 1400
-    "tx.process (1200ns)" : 1200
-    "tx.apply (1200ns)" : 1200
-    "Context inject (200ns)" : 200
-```
-
-**Transaction Tracing Overhead (~4.0μs total)**
-
-</div>
-
-**Overhead percentage**: 4.0 μs / 200 μs (avg tx processing) = **~2.0%**
-
-> **Breakdown**: Each span (tx.receive, tx.process, tx.apply) costs ~1,000 ns for creation plus
-> ~200-400 ns for 3-5 attribute sets. Context injection is ~200 ns (confirmed by benchmarks).
-> On production hardware, expect ~2.6 μs total (~1.3% overhead) due to faster span creation (~500-600 ns).
->
-> This three-span model predates the apply-pipeline instrumentation. The shipped
-> transaction path also emits `tx.preflight`, `tx.preclaim` and `tx.transactor`
-> (the spans planned here as `tx.validate`), and never emits `tx.relay`. Scale
-> the estimate by span count for a current figure: ~6 spans ≈ 7-8 μs on CI
-> hardware, ~4-5 μs on server hardware. The measured end-to-end cost is in
-> §3.5.3 (~3-4% throughput at head sampling 1.0), which supersedes this
-> bottom-up estimate.
-
-### 3.4.3 Consensus Round Overhead
-
-| Operation              | Count | Cost (ns) | Total      |
-| ---------------------- | ----- | --------- | ---------- |
-| consensus.round span   | 1     | ~1200     | ~1.2 μs    |
-| consensus.phase spans  | 3     | ~1100     | ~3.3 μs    |
-| proposal.receive spans | ~20   | ~1100     | ~22 μs     |
-| proposal.send spans    | ~3    | ~1100     | ~3.3 μs    |
-| Context operations     | ~30   | ~200      | ~6 μs      |
-| **TOTAL**              |       |           | **~36 μs** |
-
-> **Why higher**: Each span costs ~1,000 ns creation + ~100-200 ns for 1-2 attributes, totaling ~1,100-1,200 ns.
-> Context operations remain ~200 ns (confirmed by benchmarks). On production hardware, expect ~24 μs total.
->
-> The "1-2 attributes" figure understates the shipped consensus spans, which are
-> the attribute-rich ones: `consensus.accept.apply` alone sets 13
-> (`RCLConsensus.cpp:600-674`). Adding ~1 μs per such span still leaves the
-> round total under ~40 μs against a ~3 s round, so the conclusion below is
-> unaffected. Note also that the `consensus.phase` row covers the shipped names
-> `consensus.phase.open`, `consensus.establish` and `consensus.accept` — see
-> [02 §2.3.2](./02-design-decisions.md).
-
-**Overhead percentage**: 36 μs / 3s (typical round) = **~0.001%** (negligible)
-
-### 3.4.4 RPC Request Overhead
-
-| Operation                                  | Cost (ns)    |
-| ------------------------------------------ | ------------ |
-| `rpc.http_request` / `rpc.ws_message` span | ~1200        |
-| `rpc.command.*` span                       | ~1100        |
-| Context extract                            | ~250         |
-| Context inject                             | ~200         |
-| **TOTAL**                                  | **~2.75 μs** |
-
-> **Why higher**: Each span costs ~1,000 ns creation + ~100-200 ns for attributes (command name,
-> version, role). Context extract/inject costs are confirmed by OTel C++ benchmarks.
-
-- Fast RPC (1ms): 2.75 μs / 1ms = **~0.275%**
-- Slow RPC (100ms): 2.75 μs / 100ms = **~0.003%**
-
----
-
-## 3.5 Memory Overhead Analysis
-
-> **OTLP** = OpenTelemetry Protocol
-
-### 3.5.1 Static Memory
-
-| Component                            | Size        | Allocated  |
-| ------------------------------------ | ----------- | ---------- |
-| TracerProvider singleton             | ~64 KB      | At startup |
-| BatchSpanProcessor (circular buffer) | ~16 KB      | At startup |
-| BatchSpanProcessor (worker thread)   | ~8 MB       | At startup |
-| OTLP/HTTP exporter (client init)     | ~64 KB      | At startup |
-| Propagator registry                  | ~8 KB       | At startup |
-| **Total static**                     | **~8.1 MB** |            |
-
-> **Why higher than earlier estimate**: The BatchSpanProcessor's circular buffer itself is only ~16 KB
-> (2049 x 8-byte `AtomicUniquePtr` entries), but it spawns a dedicated worker thread whose default
-> stack size on Linux is ~8 MB. The OTLP/HTTP exporter allocates a small client and TLS
-> initialization buffer. The worker thread stack dominates the static footprint.
-
-### 3.5.2 Dynamic Memory
-
-| Component            | Size per unit  | Max units  | Peak            |
-| -------------------- | -------------- | ---------- | --------------- |
-| Active span          | ~500-800 bytes | 1000       | ~500-800 KB     |
-| Queued span (export) | ~500 bytes     | 2048       | ~1 MB           |
-| Attribute storage    | ~80 bytes      | 5 per span | Included        |
-| Context storage      | ~64 bytes      | Per thread | ~6.4 KB         |
-| **Total dynamic**    |                |            | **~1.5-1.8 MB** |
-
-> **Why active spans are larger**: An active `Span` object includes the wrapper (~88 bytes: shared_ptr,
-> mutex, unique_ptr to Recordable) plus `SpanData` (~250 bytes: SpanContext, timestamps, name, status,
-> empty containers) plus attribute storage (~200-500 bytes for 3-5 string attributes in a `std::map`).
-> Source: `sdk/src/trace/span.h` and `sdk/include/opentelemetry/sdk/trace/span_data.h`.
-> Queued spans release the wrapper, keeping only `SpanData` + attributes (~500 bytes).
-
-### 3.5.3 Memory Growth Characteristics
-
-```mermaid
----
-config:
-    xyChart:
-        width: 700
-        height: 400
----
-xychart-beta
-    title "Memory Usage vs Span Rate (bounded by queue limit)"
-    x-axis "Spans/second" [0, 200, 400, 600, 800, 1000]
-    y-axis "Memory (MB)" 0 --> 12
-    line [8.5, 9.2, 9.6, 9.9, 10.0, 10.0]
-```
-
-**Notes**:
-
-- Memory increases with span rate but **plateaus at queue capacity** (default 2048 spans)
-- Batch export prevents unbounded growth
-- At queue limit, oldest spans are dropped (not blocked)
-- Maximum memory is bounded: ~8.3 MB static (dominated by worker thread stack) + 2048 queued spans x ~500 bytes (~1 MB) + active spans (~0.8 MB) ≈ **~10 MB ceiling**
-- The worker thread stack (~8 MB) is virtual memory; actual RSS depends on stack usage (typically much less)
-
-> **Measured outcome**: A perf-iac comparison (telemetry compiled-in + enabled vs compiled-out,
-> 9 nodes — validators and client-handlers — under sustained payment load) recorded **no measurable
-> RSS increase over the telemetry-off baseline** (~15 GiB mean / ~18–19 GiB peak on both sides),
-> with no OOM, no swap, and no leak across the run. The ~10 MB ceiling above is therefore a
-> provisioning safety margin (dominated by virtual thread-stack address space), not an expected
-> resident-memory increase. Steady-state cost shows up as throughput (~3–4% at head sampling 1.0),
-> not memory.
-
-### 3.5.4 Performance Data Sources
-
-The overhead estimates in Sections 3.3-3.5 are derived from the following sources:
-
-| Source                                           | What it covers                                        | URL                                                                                                                                        |
-| ------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| OTel C++ SDK CI benchmarks (969 runs)            | Span creation, context activation, sampler overhead   | [Benchmark Dashboard](https://open-telemetry.github.io/opentelemetry-cpp/benchmarks/)                                                      |
-| `api/test/trace/span_benchmark.cc`               | API-level span creation (~22 ns no-op)                | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/api/test/trace/span_benchmark.cc)                                   |
-| `sdk/test/trace/sampler_benchmark.cc`            | SDK span creation with samplers (~1,000 ns AlwaysOn)  | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/test/trace/sampler_benchmark.cc)                                |
-| `sdk/include/.../span_data.h`                    | SpanData memory layout (~250 bytes base)              | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/include/opentelemetry/sdk/trace/span_data.h)                    |
-| `sdk/src/trace/span.h`                           | Span wrapper memory layout (~88 bytes)                | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/src/trace/span.h)                                               |
-| `sdk/include/.../batch_span_processor_options.h` | Default queue size (2048), batch size (512)           | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/include/opentelemetry/sdk/trace/batch_span_processor_options.h) |
-| `sdk/include/.../circular_buffer.h`              | CircularBuffer implementation (AtomicUniquePtr array) | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/include/opentelemetry/sdk/common/circular_buffer.h)             |
-| OTLP proto definition                            | Serialized span size estimation                       | [Proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto)                          |
-
----
-
-## 3.6 Network Overhead Analysis
-
-### 3.6.1 Export Bandwidth
-
-> **Bytes per span**: Estimates use ~500 bytes/span (conservative upper bound). OTLP protobuf analysis
-> shows a typical span with 3-5 string attributes serializes to ~200-300 bytes raw; with gzip
-> compression (~60-70% of raw) and batching (amortized headers), ~350 bytes/span is more realistic.
-> The table uses the conservative estimate for capacity planning.
-
-**Node → collector bandwidth is always the 100% row.** Head sampling is a
-`static constexpr` 1.0 (`Telemetry.h:234`) with no config key, so every node
-exports every span and the export bandwidth is not tunable from `xrpld.cfg`.
-
-| Sampling Rate         | Spans/sec | Bandwidth  | Where it applies                                                                                                                    |
-| --------------------- | --------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| 100%                  | ~500      | ~250 KB/s  | **The only reachable node→collector figure.** Plan capacity against this row                                                        |
-| 0.5%                  | ~2.5      | ~1.25 KB/s | Collector→backend only, and only with the Grafana Cloud overlay's `tail_sampling` (`otel-collector-config.grafanacloud.yaml:60-67`) |
-| 10% / 1% / error-only | —         | —          | **Not implemented.** No shipped config produces these ratios; treat them as illustrative of what a tail-sampling policy could do    |
-
-The rows below 100% therefore reduce _storage_ cost at the backend, never the
-node's egress. Note also that the shipped 0.5% policy is applied to the
-trace-storage branch only, so the spanmetrics-derived RED metrics still see
-100% of spans and stay exact.
-
-### 3.6.2 Trace Context Propagation
-
-| Message Type           | Context Size | Messages/sec | Overhead    |
-| ---------------------- | ------------ | ------------ | ----------- |
-| TMTransaction          | 25 bytes     | ~100         | ~2.5 KB/s   |
-| TMProposeSet           | 25 bytes     | ~10          | ~250 B/s    |
-| TMValidation           | 25 bytes     | ~50          | ~1.25 KB/s  |
-| **Total P2P overhead** |              |              | **~4 KB/s** |
-
----
-
-## 3.7 Optimization Strategies
-
-### 3.7.1 Sampling Strategies
-
-#### Head Sampling (node) — fixed, not a decision point
-
-There is no sampling decision on the node. `samplingRatio` is a
-`static constexpr double = 1.0` (`Telemetry.h:234`) and `TelemetryConfig.cpp:139`
-records why nothing is parsed: a per-node ratio would let two nodes make
-opposite keep/drop decisions for the same distributed trace, yielding partial
-traces. The ratio sampler is wrapped in a `ParentBasedSampler` so a span with a
-remote parent honours the upstream flag. The only node-local way to drop a span
-is the explicit, per-call-site `SpanGuard::discard()`, enforced downstream by
-`FilteringSpanProcessor`.
-
-#### Tail Sampling (collector) — aspirational shape
-
-The flowchart below is a **design sketch of a multi-policy tail sampler. It is
-not what ships.** The base collector config has no `tail_sampling` processor at
-all; the Grafana Cloud overlay has exactly one `probabilistic` policy at 0.5%
-with no error or latency carve-outs. Read it as a template for a policy you
-might write, not as a description of this repo — and note that adding
-error/latency policies would need `decision_wait` tuning, since a policy can
-only see spans that arrived within that window.
-
-```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{"Probabilistic keep?<br/>(shipped policy: 0.5%)"}
-
-    prob -->|Yes| sample
-    prob -->|No| drop["DROP"]
-
-    style sample fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style drop fill:#b71c1c,stroke:#7f1d1d,color:#fff
-    style trace fill:#0d47a1,stroke:#082f6a,color:#fff
-    style errors fill:#334155,stroke:#1e293b,color:#fff
-    style consensus fill:#334155,stroke:#1e293b,color:#fff
-    style slow fill:#334155,stroke:#1e293b,color:#fff
-    style prob fill:#334155,stroke:#1e293b,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
-
-Instrumentation is gated on two levels. A compile-time feature flag reduces the trace macros to no-ops when telemetry is built out, so disabled builds carry zero cost. At runtime, per-component guards (e.g. `shouldTracePeer()`) skip span creation for components whose tracing is turned off, incurring no overhead beyond a single boolean check.
-
-> The compile-time gate is the macro `XRPL_ENABLE_TELEMETRY`, but that macro is
-> **not** the switch you flip. It is a compile definition added by
-> `CMakeLists.txt` (`add_compile_definitions(XRPL_ENABLE_TELEMETRY)`) when the CMake option `telemetry` is ON.
-> That option is declared ON today (`option(telemetry "Enable OpenTelemetry tracing" ON)`)
-> only so that CI compiles the instrumented build while the telemetry branches are
-> in review; **OFF is the intended default once merged**, flipped in a separate
-> change. Select the value explicitly instead of relying on the default:
-> `-Dtelemetry=ON|OFF` (CMake) or `-o telemetry=True|False` (Conan). See
-> [05 §5.4.2](./05-configuration-reference.md).
-
----
-
-## 3.8 Links to Detailed Documentation
-
-- **[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
-
-> **TxQ** = Transaction Queue
-
-This section provides a detailed assessment of how intrusive the OpenTelemetry integration is to the existing xrpld codebase.
-
-### 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.55]
-    Transaction Relay: [0.55, 0.85]
-    Consensus Tracing: [0.75, 0.92]
-    Peer Message Tracing: [0.85, 0.35]
-    JobQueue Context: [0.3, 0.42]
-    Ledger Acquisition: [0.48, 0.65]
-    PathFinding: [0.38, 0.72]
-    TxQ and Fees: [0.25, 0.62]
-    Validator Mgmt: [0.15, 0.35]
-```
-
-**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**        | Minimal | Read-only instrumentation; no modification to consensus or transaction data flow                                                                                                                                                                                                                                                                                                                                                                     |
-| **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     | A single CMake option (`telemetry`) selects the whole feature in or out, and builds work either way (`-Dtelemetry=ON` / `-Dtelemetry=OFF`). It is declared ON today only so CI compiles the instrumented paths; **OFF is the intended default once merged**, so the shipped build is opt-in                                                                                                                                                          |
-| **Dependencies**     | Medium  | `opentelemetry-cpp/1.28.0` is a **conditional** requirement, never a hard one: `conanfile.py:152-153` adds it only `if self.options.telemetry`, and `:238-239` adds the matching `libxrpl` component requirement the same way. The option's declared default is `True` today (`conanfile.py:59`), so a default `conan install` does resolve it; with `-o telemetry=False` it never enters the graph and the null implementation supplies the factory |
-
-### 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 | `-Dtelemetry=OFF` (or `-o telemetry=False`) produces a binary with all tracing compiled out, whatever the option's declared default happens to be. **Not** `-DXRPL_ENABLE_TELEMETRY=OFF`, which does not disable anything — it is not a CMake option, only a compile definition that `CMakeLists.txt:152` adds inside the `if(telemetry)` block. CMake does flag it (`Manually-specified variables were not used by the project`) at the end of configuration, so it is not literally silent — but the warning is easy to scroll past and the resulting binary still has telemetry compiled in. See [05 §5.4.2](./05-configuration-reference.md) |
-| **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 `[telemetry]` and restart (zero code change).
-   Also set `[insight] server=` to something other than `otel` if metrics must
-   stop too — `enabled=0` governs tracing, and the metrics pipeline is selected
-   separately ([02 §2.6.4](./02-design-decisions.md)).
-2. **Quick**: Rebuild with `-Dtelemetry=OFF` (CMake) or `-o telemetry=False`
-   (Conan). Pass the flag explicitly — an omitted flag resolves to the option's
-   declared default, which is ON today and OFF once the feature is merged; a
-   build that already has telemetry off needs no rebuild at all.
-   **Do not use `-DXRPL_ENABLE_TELEMETRY=OFF`** — it is not a CMake option, so
-   it is ignored (CMake reports it under `Manually-specified variables were not
-used by the project`) and the rebuilt binary still has telemetry compiled in.
-   This step also drops the `opentelemetry-cpp` dependency, so expect a full
-   rebuild rather than an incremental one.
-3. **Complete**: Revert telemetry commits (clean separation makes this easy)
-
-### 3.9.7 Code Change Examples
-
-**Minimal RPC Instrumentation (Low Intrusiveness):** Instrumenting an RPC handler adds roughly 3-4 lines: one macro to start the span and one or two `setAttribute` calls (command name, status). The span ends automatically via RAII, so the existing control flow — process the request, send the result — is untouched.
-
-**Consensus Instrumentation (Medium Intrusiveness):** Consensus is slightly more intrusive because child spans in later phase transitions need the round's context. Beyond the span-start and attribute macros, this requires **four** new member variables on the adaptor rather than the single `currentRoundContext_` this section originally sketched (`RCLConsensus.h:103,113,123,143`):
-
-- `std::optional<telemetry::SpanGuard> roundSpan_` (`:103`) — the round span
-  itself. It is **created and ended in one place**, `startRoundTracing()`: the
-  previous round's guard is released at `RCLConsensus.cpp:1288-1289`
-  (`if (roundSpan_) roundSpan_.reset();`) and the new one is emplaced a few
-  lines later — at `:1306` or `:1310` on the `"attribute"` strategy, at `:1319`
-  on the default `"deterministic"` one. `preStartRound()` does not create it; it
-  calls `startRoundTracing()` at `:1229`. There is no `reset()` method — the
-  span simply lives until the next round begins. A `SpanGuard` owns no
-  thread-local scope, so emplacing and resetting on different job workers is
-  safe.
-- `telemetry::SpanContext roundSpanContext_` (`:113`) — a lightweight value-type
-  snapshot, captured at the end of `startRoundTracing()` (`:1350`). Child spans
-  link through this, not through an ambient parent, so code running on another
-  worker (e.g. `createValidationSpan()` on `jtACCEPT`) never touches
-  `roundSpan_` cross-thread.
-- `telemetry::SpanContext prevRoundSpanContext_` (`:123`) — the prior round's
-  context, saved at `:1282` **before** the new span overwrites
-  `roundSpanContext_`, so the new round span can carry a follows-from link and
-  consecutive rounds stay navigable.
-- `telemetry::SpanContext acceptSpanContext_` (`:143`) — the current round's
-  accept-span context, set at `:544` and cleared at `:1286` on each new round.
-  `createValidationSpan()` prefers it as the parent and falls back to
-  `roundSpanContext_` (`:1363-1373`), so a stale value must not survive into the
-  next round.
-
-The split is the point: the guard is owned by one thread, the contexts are
-copied freely. The existing round logic itself remains unchanged.
-
----
-
-_Previous: [Design Decisions](./02-design-decisions.md)_ | _Next: [Configuration Reference](./05-configuration-reference.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/05-configuration-reference.md

@@ -1,699 +0,0 @@
-# Configuration Reference
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Implementation Phases](./06-implementation-phases.md)
-
----
-
-## 5.1 xrpld Configuration
-
-> **OTLP** = OpenTelemetry Protocol | **TxQ** = Transaction Queue
-
-### 5.1.1 Configuration File Section
-
-The authoritative `[telemetry]` example lives in `cfg/xrpld-example.cfg`. Telemetry is disabled by default (`enabled=0`); enabling it turns on distributed tracing for transaction flow, consensus, and RPC calls, with traces exported to an OpenTelemetry Collector over OTLP. Head sampling is intentionally fixed at 1.0 (sample everything) and is not configurable — per-node head-sampling would produce broken/partial distributed traces, so volume reduction is delegated to the collector's tail sampling (see Section 7.4.2). Transaction trace IDs are always deterministic (`trace_id = txHash[0:16]`); there is no strategy switch for the transaction path. The full option reference follows.
-
-> **`service_instance_id` is effectively required for `beast::insight`
-> metrics — and only for those.** Three producers resolve the instance id
-> independently, and exactly one of them lacks a node-key fallback:
->
-> | Producer                                    | Resource built by                            | Unset `service_instance_id` yields             |
-> | ------------------------------------------- | -------------------------------------------- | ---------------------------------------------- |
-> | Traces (and therefore all `span_*` metrics) | `Telemetry::start()`                         | Base58 node public key                         |
-> | Native `XRPL_METRIC_*` (`MetricsRegistry`)  | `MetricsRegistry::initExporterAndProvider()` | Base58 node public key                         |
-> | `beast::insight` (`[insight] server=otel`)  | `TelemetryImpl` **constructor**              | **`service.instance.id` absent** — no fallback |
->
-> - **Traces**: the tracer resource is built in `Telemetry::start()`
->   (`Telemetry.cpp:380-387`), which runs after `ApplicationImp::setup()` has
->   called `setServiceInstanceId()` (`Application.cpp:1323`) with the Base58
->   node public key. An unset key therefore still yields the node key. The
->   `spanmetrics` connector derives `span_calls_total` /
->   `span_duration_milliseconds_*` from those spans, so span metrics inherit
->   the correct id too.
-> - **Native `XRPL_METRIC_*` metrics** build their **own** MeterProvider
->   resource in `MetricsRegistry::initExporterAndProvider()`
->   (`MetricsRegistry.cpp:280`, `:296-304`, provider created at `:339`), and
->   `ApplicationImp::startTelemetry()` supplies the id with an explicit node-key
->   fallback (`Application.cpp:1674-1679`: read the config key, and
->   `if (instanceId.empty() && nodeIdentity_)` substitute
->   `toBase58(TokenType::NodePublic, …)`). By then `setup()` has resolved
->   `nodeIdentity_` (`Application.cpp:1315`), so these metrics carry the node
->   key even with the config key unset.
-> - **`beast::insight` metrics** are the exception. They use the **global**
->   MeterProvider, whose resource is built in the `TelemetryImpl`
->   **constructor** (`Telemetry.cpp:321-338`, `initMetrics()` at `:447`),
->   because insight instruments are created eagerly in subsystem constructors
->   and would otherwise bind to the noop provider forever. At that point
->   `serviceInstanceId` is still `""` (`Application.cpp:348` passes an empty
->   node key), and the code comment at `Telemetry.cpp:333-336` states plainly
->   that the later setter "cannot change this immutable resource". Worse,
->   `initMetrics()` sets the attribute **unconditionally**
->   (`Telemetry.cpp:488`), so the resource carries `service.instance.id=""`
->   rather than omitting it — whereas `MetricsRegistry` guards the same write
->   with `if (!instanceId.empty())` (`MetricsRegistry.cpp:302-303`).
->
-> Result: with `service_instance_id` unset, `beast::insight` metrics — and only
-> those — export with an empty `service.instance.id`. Every shipped Grafana
-> dashboard filters on `service_instance_id=~"$node"`, so **insight-backed
-> panels** lose their per-node dimension; span-metric and `XRPL_METRIC_*`
-> panels are unaffected. Set the key explicitly on any node whose insight
-> metrics are dashboarded.
->
-> **Known issue.** The asymmetry is a defect, not a design: `MetricsRegistry`
-> already demonstrates the node-key fallback that the global provider needs.
-> A fix would have to resolve the node identity before `TelemetryImpl` is
-> constructed, or make the insight metrics use a late-built provider.
-
-### 5.1.2 Configuration Options Summary
-
-| Option                     | Type   | Default                            | Description                                                                                                                                                                                                                           |
-| -------------------------- | ------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `enabled`                  | 0 or 1 | `0`                                | Enable/disable telemetry                                                                                                                                                                                                              |
-| `endpoint`                 | string | `http://localhost:4318/v1/traces`  | OTLP/HTTP collector endpoint for **traces**                                                                                                                                                                                           |
-| `metrics_endpoint`         | string | `http://localhost:4318/v1/metrics` | OTLP/HTTP collector endpoint for the native metrics pipeline (`MetricsRegistry`). Read in `Application.cpp:1670`                                                                                                                      |
-| `use_tls`                  | 0 or 1 | `0`                                | Enable TLS for exporter connection                                                                                                                                                                                                    |
-| `tls_ca_cert`              | string | `""`                               | Path to CA certificate file                                                                                                                                                                                                           |
-| `tls_client_cert`          | string | `""`                               | Client cert (PEM) for mTLS; empty = one-way; if `enabled=1`, needs key + `use_tls=1` or startup fails                                                                                                                                 |
-| `tls_client_key`           | string | `""`                               | Private key (PEM) for `tls_client_cert`; if set with `enabled=1`, needs the cert + `use_tls=1` or fails                                                                                                                               |
-| `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   | `true`                             | Enable peer message tracing (high volume)                                                                                                                                                                                             |
-| `trace_ledger`             | bool   | `true`                             | Enable ledger tracing                                                                                                                                                                                                                 |
-| `consensus_trace_strategy` | string | `"deterministic"`                  | Consensus trace ID strategy: `"deterministic"` (trace_id = prevLedgerHash[0:16]) or `"attribute"` (random). Parsed at `TelemetryConfig.cpp:155-156`, consumed at `RCLConsensus.cpp:1291,1296`. **Not validated** — see the note below |
-| `service_name`             | string | `"xrpld"`                          | Service name (`service.name`) for traces and metrics                                                                                                                                                                                  |
-| `service_instance_id`      | string | node public key (base58)           | Instance identifier (`service.instance.id`). Traces, span metrics and native `XRPL_METRIC_*` metrics all fall back to the node key; **`beast::insight` metrics do not** — see the note in §5.1.1                                      |
-
-**`consensus_trace_strategy` is not validated.** `TelemetryConfig.cpp:155-156`
-copies the raw string into `Setup::consensusTraceStrategy` without checking it
-against an allowed set, and the only comparison in the code is
-`strategy == "attribute"` (`RCLConsensus.cpp:1296`). Any unrecognised value —
-including a typo — silently takes the deterministic branch with no log warning.
-The two accepted values are documented at `include/xrpl/telemetry/Telemetry.h:287-292`.
-
-**Not a config key — deterministic transaction trace IDs are unconditional.**
-Earlier drafts of this document listed a `tx_trace_strategy` option
-(`"deterministic"` \| `"attribute"`). No such key exists: `TelemetryConfig.cpp`
-parses no transaction-strategy key, and the transaction trace ID is always
-derived from the transaction hash. Only the **consensus** path has a
-switchable strategy.
-
-**Planned (not yet implemented)**: the following options appear in the design
-documents but are not parsed by `TelemetryConfig.cpp`. They will be added as
-the corresponding subsystems are instrumented:
-
-| Option            | Planned Phase | Purpose                                  |
-| ----------------- | ------------- | ---------------------------------------- |
-| `exporter`        | Future        | Select between OTLP/HTTP and OTLP/gRPC   |
-| `trace_pathfind`  | Phase 2       | Path computation tracing toggle          |
-| `trace_txq`       | Phase 3       | Transaction queue tracing toggle         |
-| `trace_validator` | Future        | Validator list / manifest update tracing |
-| `trace_amendment` | Future        | Amendment voting tracing                 |
-
-> **`exporter` is not read, so do not set it.** Both shipped sample configs
-> (`docker/telemetry/xrpld-telemetry.cfg`,
-> `docker/telemetry/xrpld-telemetry-mainnet.cfg`) used to carry
-> `exporter=otlp_http`; the line had no effect and has since been replaced with
-> a comment saying so. OTLP/HTTP is the only transport that exists (§2.2.1), and
-> `endpoint` / `metrics_endpoint` are the only transport knobs, until the §2.2.2
-> gRPC work lands.
-
----
-
-## 5.2 Configuration Parser
-
-> **TxQ** = Transaction Queue
-
-The parser `makeTelemetrySetup()` in `src/libxrpl/telemetry/TelemetryConfig.cpp` reads the `[telemetry]` `Section` and populates a `Telemetry::Setup` struct, applying the defaults listed in Section 5.1.2 via `section.valueOr(...)`. It takes `serviceInstanceId` from the `nodePublicKey` argument when the key is absent, applies one unconditional `endpoint` default (`dflt::endpoint`, `TelemetryConfig.cpp:61`, used at `:108`) — the parser has no notion of exporter type — and leaves the sampling ratio at its fixed 1.0 default (a `static constexpr` member, so there is nothing to parse; `TelemetryConfig.cpp:139`, `Telemetry.h:234`). It also rejects two contradictory mTLS configurations outright (`tls_client_cert` without `tls_client_key`, and either without `use_tls=1`) rather than failing open at handshake time.
-
-`metrics_endpoint` is deliberately **not** handled here: it is read separately in `ApplicationImp::startTelemetry()` (`Application.cpp:1670`) and passed to `MetricsRegistry::start()`. Note the consequence — the two metric exporters resolve their URL differently:
-
-| Metric source                              | Exporter built by                            | URL comes from                                                       |
-| ------------------------------------------ | -------------------------------------------- | -------------------------------------------------------------------- |
-| `beast::insight` (`[insight] server=otel`) | `Telemetry::initMetrics()` (global provider) | `endpoint` with a trailing `/v1/traces` rewritten to `/v1/metrics`   |
-| Native `XRPL_METRIC_*` (`MetricsRegistry`) | `MetricsRegistry::initExporterAndProvider()` | `metrics_endpoint`, defaulting to `http://localhost:4318/v1/metrics` |
-
-Setting a non-default `endpoint` therefore moves the insight metrics with it, but leaves the native metrics on localhost unless `metrics_endpoint` is set too.
-
----
-
-## 5.3 Application Integration
-
-### 5.3.1 ApplicationImp Changes
-
-> **Deferred identity**: The node public key (`nodeIdentity_`) is not
-> available during `ApplicationImp`'s member initializer list — it is
-> resolved later in `setup()`. The `Telemetry` object is therefore
-> constructed with an empty `serviceInstanceId` and patched via
-> `setServiceInstanceId()` once `setup()` has called `getNodeIdentity()`.
-> **This patch reaches traces only.** The **global** MeterProvider resource —
-> the one `beast::insight` metrics use — is already frozen by then (§5.1.1), so
-> those metrics keep whatever `service_instance_id` the config supplied (`""`
-> if it supplied none). Native `XRPL_METRIC_*` metrics do not go through this
-> patch at all: `startTelemetry()` re-reads the config key and applies its own
-> node-key fallback when building `MetricsRegistry`'s separate resource
-> (`Application.cpp:1674-1679`).
-
-`ApplicationImp` (in `src/xrpld/app/main/Application.cpp`) owns a `std::unique_ptr<telemetry::Telemetry> telemetry_`. It is built in the member initializer list via `makeTelemetry(makeTelemetrySetup(...))` with an empty `serviceInstanceId`, then patched in `setup()` by calling `setServiceInstanceId()` with the Base58 node public key (unless the user supplied a custom `service_instance_id`). `start()` and `run()` forward to `telemetry_->start()` / `telemetry_->stop()`, and `getTelemetry()` returns the owned instance.
-
-### 5.3.2 ServiceRegistry Interface Addition
-
-`include/xrpl/core/ServiceRegistry.h` gains a pure-virtual `telemetry::Telemetry& getTelemetry()` (with a forward declaration of `telemetry::Telemetry`), giving every component a uniform accessor for the tracing subsystem.
-
-> **Note:** `Application` extends `ServiceRegistry`, so `getTelemetry()` is
-> available on both. Components that hold a `ServiceRegistry&` (e.g.
-> `NetworkOPsImp`) call `registry_.get().getTelemetry()`. Components that
-> still hold an `Application&` (e.g. `ServerHandler`, `PeerImp`,
-> `RCLConsensusAdaptor`) call `app_.getTelemetry()` directly.
-
----
-
-## 5.4 CMake Integration
-
-> **OTLP** = OpenTelemetry Protocol
-
-### 5.4.1 Locating the OpenTelemetry SDK
-
-> **Superseded design.** Earlier drafts described a hand-written
-> `cmake/FindOpenTelemetry.cmake` module that aliased `OpenTelemetry::api`,
-> `OpenTelemetry::sdk` and `OpenTelemetry::otlp_grpc_exporter` with a
-> `pkg-config` fallback. That module was never written — it exists in no
-> commit — and the aliasing approach it described does not work with the
-> package the build actually consumes.
-
-The SDK is located by the Conan-generated CMake config package, nothing else:
-
-- `CMakeLists.txt` — `find_package(opentelemetry-cpp CONFIG REQUIRED)`,
-  guarded by the `telemetry` option (§5.4.2). The dependency itself is
-  declared in `conanfile.py:153` (`opentelemetry-cpp/1.28.0`), also guarded —
-  `requirements()` adds it only `if self.options.telemetry` (`:152`), so with
-  the option off the package never enters the dependency graph.
-- Linking goes through the **umbrella** target
-  `opentelemetry-cpp::opentelemetry-cpp`, never the per-component targets.
-  `cmake/XrplCore.cmake:221-225` and `:83-91` record why: the Conan package
-  under-declares its inter-component dependencies, so naming `::api` / `::sdk`
-  individually produces the wrong static-link order and fails at executable
-  link time. The umbrella target supplies both the trace and metrics
-  components with the correct ordering.
-
-### 5.4.2 CMakeLists.txt Changes
-
-The build flag is `telemetry`:
-
-```
-option(telemetry "Enable OpenTelemetry tracing" ON)   # top-level CMakeLists.txt
-```
-
-The declared value is ON **temporarily**, so that CI compiles the telemetry code
-paths while the feature branches are in review. **OFF is the intended default
-once merged**, and the flip is a separate change. Set the value explicitly
-rather than relying on the default:
-
-| To …                      | Use (CMake)       | Use (Conan)          |
-| ------------------------- | ----------------- | -------------------- |
-| Build telemetry in        | `-Dtelemetry=ON`  | `-o telemetry=True`  |
-| Build it out (all no-ops) | `-Dtelemetry=OFF` | `-o telemetry=False` |
-
-When the option is ON, the guarded block below it runs
-`find_package(opentelemetry-cpp CONFIG REQUIRED)` and adds the
-**compile definition** `XRPL_ENABLE_TELEMETRY`.
-
-> **`XRPL_ENABLE_TELEMETRY` is not a CMake option.** It is only ever _added_
-> as a compile definition by `add_compile_definitions(XRPL_ENABLE_TELEMETRY)` in that same block. Passing
-> `-DXRPL_ENABLE_TELEMETRY=OFF` on the CMake command line disables **nothing** —
-> it defines an unused cache variable and telemetry stays compiled in. CMake does
-> report it, at the end of configuration under `Manually-specified variables were
-not used by the project`, so it is not literally silent — but that line is easy
-> to scroll past. Any procedure that relies on it (including the rollback path in
-> [§3.9.6](./03-implementation-strategy.md)) must use `-Dtelemetry=OFF`.
-
-The target is `xrpl.libxrpl.telemetry`, created by `add_module(xrpl telemetry)`
-at `cmake/XrplCore.cmake:231` from `include/xrpl/telemetry/` +
-`src/libxrpl/telemetry/`. There is no `xrpl_telemetry` target.
-
-Selection between the real and the no-op implementation is an **in-source
-`#ifdef`, not a source swap**: `NullTelemetry.cpp` is compiled into the target
-unconditionally (see its header comment, `NullTelemetry.cpp:1-12`). It provides
-the `makeTelemetry()` factory when `XRPL_ENABLE_TELEMETRY` is undefined; when
-the macro is defined, `Telemetry.cpp` provides the factory instead and
-`NullTelemetry`'s virtuals only serve as noop tracer/span fallbacks. Call sites
-compile unchanged either way.
-
----
-
-## 5.5 OpenTelemetry Collector Configuration
-
-> **OTLP** = OpenTelemetry Protocol | **APM** = Application Performance Monitoring
-
-> **Production hardening**: The configurations in this section are starting points. For production deployments where xrpld ships telemetry across a network to a centrally-hosted collector, see [Securing the OTel Pipeline](./secure-OTel.md) for the required mTLS receiver config, NetworkPolicy, and peer trace-context validation.
-
-The authoritative collector config lives in the repo at `docker/telemetry/otel-collector-config.yaml` (with Tempo backend config in `docker/telemetry/tempo.yaml`). The sections below summarize the development and production shapes of that pipeline.
-
-### 5.5.1 Development / Base Configuration
-
-`docker/telemetry/otel-collector-config.yaml` is the base config used by the
-local stack and by CI. It carries **three** pipelines, not one:
-
-| Pipeline  | Receivers             | Processors                                                       | Exporters                            |
-| --------- | --------------------- | ---------------------------------------------------------------- | ------------------------------------ |
-| `traces`  | `otlp`                | `resource/tier`, `resource/stripsdk`, `attributes/hash`, `batch` | `debug`, `otlp/tempo`, `spanmetrics` |
-| `metrics` | `otlp`, `spanmetrics` | `resource/tier`, `resource/stripsdk`, `batch`                    | `prometheus`                         |
-| `logs`    | `filelog`             | `resource/logs`, `resource/tier`, `resource/stripsdk`, `batch`   | `otlphttp/loki`                      |
-
-Component detail:
-
-- **Receivers.** `otlp` on gRPC `0.0.0.0:4317` and HTTP `0.0.0.0:4318` (both
-  traces and native metrics arrive on 4318). `filelog` tails
-  `/var/log/xrpld/*/debug.log` and runs a `regex_parser` that lifts
-  `timestamp`, `partition`, `severity` and the optional `trace_id`/`span_id`
-  emitted by the journal sink (§5.8.5).
-- **Processors.** `batch` (1s timeout, `send_batch_size: 100`);
-  `resource/tier` (`action: upsert` on `deployment.environment`, `action: insert` on
-  `xrpl.network.type` only when absent); `resource/stripsdk` (drops the
-  `telemetry.sdk.*` attributes); `resource/logs` (`action: upsert` on
-  `service.name` and `job` — only the former becomes a Loki stream label, see
-  the known issue in §5.8.5); `attributes/hash` (hashes
-  `pathfind_source_account` and `pathfind_dest_account`).
-- **Connector.** `spanmetrics` with `namespace: "span"`
-  (`otel-collector-config.yaml:114`) — this is why the derived RED metrics are
-  `span_calls_total` / `span_duration_milliseconds_*`. The connector's own
-  default namespace is **empty**, so without this setting the names would be
-  the bare `calls_total` / `duration_milliseconds_*`. The
-  `traces_spanmetrics_*` family is **not** the connector's default and is not
-  produced here at all — it comes from a different producer, Tempo's
-  `metrics_generator` `span-metrics` processor (`tempo.yaml:75`), whose
-  `remote_write` is commented out in this repo (see §5.8.6). Histogram
-  `unit: ms`
-  with sub-millisecond buckets from `0.01ms`, plus explicit `2s`–`30s`
-  boundaries for consensus and `ledger.acquire`. ~25 low-cardinality
-  dimensions are promoted to labels (`command`, `rpc_status`, `tx_type`,
-  `ter_result`, `stage`, `consensus_mode`, `outcome`, …).
-- **Exporters.** `debug` (console, `verbosity: detailed`), `otlp/tempo`
-  (`tempo:4317`, `tls.insecure: true`), `otlphttp/loki`
-  (`http://loki:3100/otlp` — Loki 3.x native OTLP; the old `loki` exporter was
-  removed in collector-contrib v0.147.0), and `prometheus` on
-  `0.0.0.0:8889` with `resource_to_telemetry_conversion.enabled: true` so the
-  tier and instance resource attributes become Prometheus labels.
-- **Extensions.** `health_check` on `0.0.0.0:13133` only. There is **no**
-  `zpages` extension.
-
-Deliberately absent from the base config — do not document them as present:
-no `memory_limiter`, no `tail_sampling`, no Elastic APM exporter, and no
-`tx_account` attribute rule (the hashed keys are the two `pathfind_*_account`
-ones).
-
-### 5.5.2 Production Configuration
-
-There is no separate "production" collector config in this repo. The one
-overlay that exists is `docker/telemetry/otel-collector-config.grafanacloud.yaml`.
-It is **not** the base config plus one processor — it restructures the service
-graph. The full delta:
-
-| Added by the overlay     | Where  | Purpose                                                                   |
-| ------------------------ | ------ | ------------------------------------------------------------------------- |
-| `basicauth/grafanacloud` | `:29`  | Extension; instance id / API token from the container environment         |
-| `tail_sampling`          | `:60`  | One `probabilistic` policy at **0.5%**, `decision_wait: 10s`              |
-| `transform/cloudlabels`  | `:119` | Copies three resource attrs onto datapoint labels for Cloud (OTLP) ingest |
-| `otlphttp/grafanacloud`  | `:236` | Single OTLP/HTTP exporter fanning all three signals to Grafana Cloud      |
-| `metrics_flush_interval` | `:136` | `spanmetrics` flushes every 15s instead of the 60s default                |
-
-| Removed by the overlay | Consequence                                                                  |
-| ---------------------- | ---------------------------------------------------------------------------- |
-| `attributes/hash`      | **Pathfinding account attributes are not hashed on this config** — see below |
-| `debug`                | No console span dump; collector logs alone when diagnosing ingest            |
-
-Pipelines go from **three** (`traces`, `metrics`, `logs`) to **five**
-(`:253-280`): `traces/metrics`, `traces/store`, `metrics/local`,
-`metrics/cloud`, `logs`. `tail_sampling` is applied in **`traces/store`**
-(`:259-261`) — the branch feeding Tempo and Grafana Cloud — not in a pipeline
-named `traces`, which does not exist in the overlay. The `traces/metrics`
-branch feeds `spanmetrics` unsampled, so the derived RED metrics stay exact
-while stored traces are ~1/200 of ingested ones.
-
-> **Known issue — the cloud path does not hash pathfinding accounts.** The base
-> config runs `attributes/hash` on its `traces` pipeline
-> (`otel-collector-config.yaml:105-110`), hashing `pathfind_source_account` and
-> `pathfind_dest_account` as defense in depth behind the node-side hashing. The
-> overlay declares no such processor and lists none on any of its five
-> pipelines, so on the Grafana Cloud config those two attributes reach **both**
-> Grafana Cloud and the local Tempo with whatever value the node sent. Any node
-> that emits raw addresses loses its second line of defense. Adding
-> `attributes/hash` to `traces/store` and `traces/metrics` would close the gap.
-
-Hardening a collector for a real deployment (TLS/mTLS on the receiver,
-NetworkPolicy, peer trace-context validation) is covered in
-[Securing the OTel Pipeline](./secure-OTel.md) — not by any config file in
-`docker/telemetry/`.
-
----
-
-## 5.6 Docker Compose Development Environment
-
-> **OTLP** = OpenTelemetry Protocol
-
-The authoritative development stack lives in the repo at `docker/telemetry/docker-compose.yml`. It brings up **six** services on a shared `xrpld-telemetry` bridge network. All images are pinned to exact tags.
-
-| Service          | Image                                          | Published ports        | Role                                                             |
-| ---------------- | ---------------------------------------------- | ---------------------- | ---------------------------------------------------------------- |
-| `otel-collector` | `otel/opentelemetry-collector-contrib:0.158.0` | `4317`, `4318`, `8889` | OTLP ingest, spanmetrics, filelog tail, Prometheus scrape target |
-| `tempo`          | `grafana/tempo:2.9.4`                          | `3200`                 | Trace storage and TraceQL                                        |
-| `loki`           | `grafana/loki:3.7.6`                           | `3100`                 | Log storage for log↔trace correlation                            |
-| `prometheus`     | `prom/prometheus:v3.13.2`                      | `9090`                 | Scrapes the collector's `:8889`                                  |
-| `grafana`        | `grafana/grafana:13.1.2`                       | `3000`                 | Dashboards + provisioned datasources/alerts, anonymous admin     |
-| `renderer`       | `grafana/grafana-image-renderer:v5.12.0`       | `8081`                 | Panel→PNG rendering for image export and alert screenshots       |
-
-Two corrections to earlier drafts:
-
-- **`prometheus` is not optional.** `grafana` lists it in `depends_on` (along
-  with `tempo`, `loki` and `renderer`), and 7 of the 15 dashboards query
-  `span_calls_total` from it. Removing it blanks most panels.
-- **Port `13133` is not published.** The collector's `health_check` extension
-  listens on `13133` inside the container, but the base compose file publishes
-  only `4317`, `4318` and `8889`. Health checks from the host must either add a
-  port mapping or run `docker compose exec`.
-
-The collector also bind-mounts the xrpld log root read-only
-(`${XRPLD_LOG_DIR:-./data/logs}` → `/var/log/xrpld`) for the `filelog`
-receiver, and the `grafana` service reads Slack/email alert secrets from an
-optional gitignored `.env.alerting`.
-
----
-
-## 5.7 Configuration Architecture
-
-> **OTLP** = OpenTelemetry Protocol
-
-```mermaid
-flowchart TB
-    subgraph config["Configuration Sources"]
-        cfgFile["xrpld.cfg<br/>[telemetry] section"]
-        cmake["CMake option: telemetry<br/>ON today for CI, OFF once merged<br/>when ON, defines XRPL_ENABLE_TELEMETRY"]
-    end
-
-    subgraph init["Initialization"]
-        parse["makeTelemetrySetup()"]
-        factory["makeTelemetry()"]
-    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
-```
-
-**Reading the diagram:**
-
-- **Configuration Sources**: `xrpld.cfg` provides runtime settings (endpoint, per-component trace toggles) while the CMake `telemetry` option controls whether telemetry is compiled in at all. That option is declared ON today only so CI compiles the instrumented paths; OFF is the intended default once merged, so treat the build gate as something to pass explicitly, and the runtime gate is opt-in either way (`enabled=0` by default). Head sampling is fixed at 1.0 and is not a config option; volume reduction happens via tail sampling in the collector.
-- **Initialization**: `makeTelemetrySetup()` parses config values, then `makeTelemetry()` constructs the provider, processor, and exporter objects.
-- **Runtime Components**: The `TracerProvider` creates spans, the `BatchProcessor` buffers them, and the `OTLP Exporter` serializes and sends them over the wire.
-- **OTLP arrow to Collector**: Trace data leaves the xrpld process via OTLP/HTTP and enters the external Collector pipeline. (OTLP/gRPC is future work — see design decisions §2.2.2.)
-- **Collector Pipeline**: `Receivers` ingest OTLP data, `Processors` apply sampling/filtering/enrichment, and `Exporters` forward traces to storage backends (Tempo, etc.).
-
----
-
-## 5.8 Grafana Integration
-
-> **APM** = Application Performance Monitoring
-
-Step-by-step instructions for integrating xrpld traces with Grafana.
-
-### 5.8.1 Data Source Configuration
-
-Three datasources are provisioned from `docker/telemetry/grafana/provisioning/datasources/`. There is **no** Elastic APM datasource — `elastic-apm.yaml` was described in an earlier draft but never existed. Elastic remains a _possible_ backend (§7.2); nothing in this repo provisions it.
-
-| File              | Type         | URL                      | uid          | Notes                                                                                                                |
-| ----------------- | ------------ | ------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------- |
-| `tempo.yaml`      | `tempo`      | `http://tempo:3200`      | `tempo`      | `nodeGraph`, `serviceMap`/`tracesToMetrics` → `prometheus`, `tracesToLogs` → `loki`, plus ~30 Explore search filters |
-| `prometheus.yaml` | `prometheus` | `http://prometheus:9090` | `prometheus` | Backs every span-metric and native-metric panel                                                                      |
-| `loki.yaml`       | `loki`       | `http://loki:3100`       | `loki`       | Backs `log-derived-insights`; derived fields jump back to Tempo                                                      |
-
-The Tempo `tracesToLogs` block is configured as `filterByTraceID: true`,
-`filterBySpanID: false`, **`tags: []`**. The empty tag list is deliberate: the
-correlation is by trace ID alone, so no span attribute needs to exist on both
-sides. Earlier drafts claimed `trace_id` + `tx_hash` tags — that is not what
-ships, and adding a tag Tempo cannot resolve blanks the link.
-
-The search-filter list is the practical index of queryable span attributes:
-resource scope (`service.name`, `service.instance.id`, `service.version`,
-`xrpl.network.id`, `xrpl.network.type`), intrinsics (`name`, `status`,
-`duration`), and span scope (`command`, `rpc_status`, `rpc_role`, `tx_hash`,
-`tx_type`, `tx_status`, `local`, `path`, `suppressed`, `peer_version`,
-`consensus_*`, `ledger_seq`, `ledger_hash`, `close_time_correct`,
-`close_resolution_ms`, `proposers`, `mode_old`, `mode_new`, `txq_status`,
-`ter_code`).
-
-### 5.8.2 Dashboard Provisioning
-
-`grafana/provisioning/dashboards/dashboards.yaml` declares a single `file`
-provider named `xrpld-telemetry`, `orgId: 1`, targeting Grafana folder `xrpld`
-from path `/var/lib/grafana/dashboards` (no `/rippled` suffix), with
-`disableDeletion: false`, `editable: true`, `foldersFromFilesStructure: false`.
-It sets **no** poll interval — Grafana's `updateIntervalSeconds` default
-applies; the "every 30s" figure in earlier drafts was invented.
-
-`docker-compose.yml` mounts `./grafana/dashboards` read-only at that path, so
-the 15 JSON files in `docker/telemetry/grafana/dashboards/` are what gets
-provisioned.
-
-### 5.8.3 Shipped Dashboards
-
-The dashboards are Prometheus-first, not TraceQL-first, and their uids are
-bare (no `xrpld-` prefix). The full inventory and per-panel query reference is
-[09-data-collection-reference.md](./09-data-collection-reference.md); the uids
-are:
-
-`consensus-health`, `fee-market`, `job-queue`, `ledger-data-sync`,
-`ledger-operations`, `log-derived-insights`, `network-traffic`, `node-health`,
-`overlay-traffic-detail`, `peer-network`, `peer-quality`, `rpc-pathfinding`,
-`rpc-performance`, `transaction-overview`, `validator-health`.
-
-> **Panel-count convention used in these docs**: counts are of **data panels
-> only** — `type: "row"` collapsible headers are excluded, because a row is a
-> layout element with no query. A board's raw `panels` array is therefore longer
-> than its stated count (e.g. `rpc-performance` has 19 array entries: 2 rows +
-> 17 data panels).
-
-Two examples described in earlier drafts do not exist and should not be looked
-for: `xrpld-rpc-performance` (the real board is `rpc-performance`, **17** data
-panels in 2 rows, mostly Prometheus span metrics) and `xrpld-tx-tracing` (the
-transaction board is `transaction-overview`, **18** data panels in 3 rows; its
-error panel filters `span_calls_total{span_name="tx.process",
-ter_result!~"tesSUCCESS|"}`, since no `tx.validate` span was ever built — see
-[02 §2.3.2](./02-design-decisions.md)).
-
-> **Why `!~"tesSUCCESS|"` and not `!="tesSUCCESS"`.** An absent Prometheus label
-> compares equal to the empty string, and `tx.process` can end **without** a
-> `ter_result` attribute: `processTransaction()` returns early when
-> `preProcessTransaction()` rejects the transaction
-> (`NetworkOPs.cpp:1437-1438`) and `doTransactionAsync()` returns early when the
-> transaction is already applying (`:1461-1462`); the only setter runs later, at
-> `:1674`. Those series carry `ter_result=""`, which `!="tesSUCCESS"` counts as
-> an error. The regex form excludes the empty value explicitly (the trailing
-> `|` alternative), which is the form `docs/telemetry-runbook.md:1198` and two
-> of the three `transaction-overview.json` failure panels already use.
-
-Every dashboard exposes a `$node` template variable bound to
-`service_instance_id`; see the §5.1.1 note on why `service_instance_id` must be
-set for metric panels to split per node.
-
-### 5.8.4 TraceQL Query Examples
-
-Common queries for xrpld traces. Every span name and attribute below is one
-that the code actually emits — check against the `*SpanNames.h` constants
-before adding more.
-
-```
-# Find all traces for a specific transaction hash
-{resource.service.name="xrpld" && span.tx_hash="ABC123..."}
-
-# Find slow RPC commands (>100ms)
-{resource.service.name="xrpld" && name=~"rpc.command.*"} | duration > 100ms
-
-# Find consensus rounds taking >5 seconds
-{resource.service.name="xrpld" && name="consensus.round"} | duration > 5s
-
-# Find failed transaction processing
-{resource.service.name="xrpld" && name="tx.process" && span.ter_result!="tesSUCCESS"}
-
-# Find failed apply-pipeline stages (preflight / preclaim / transactor)
-{resource.service.name="xrpld" && name=~"tx\\.(preflight|preclaim|transactor)" && status=error}
-
-# Find transactions that arrived from a peer rather than a local client.
-# The `local` attribute lives on tx.process, NOT on tx.receive (see the note
-# below).
-{resource.service.name="xrpld" && name="tx.process" && span.local=false}
-
-# Compare latency across nodes
-{resource.service.name="xrpld" && name="rpc.command.account_info"} | avg(duration) by (resource.service.instance.id)
-```
-
-> Queries in earlier drafts used `tx.validate`, `tx.relay` and
-> `span.relay_count`. None of the three exists: signature/format validation
-> ships as `tx.preflight`/`tx.preclaim`, and no relay span or relay-count
-> attribute was ever built. See [02 §2.3.2](./02-design-decisions.md).
-
-> **TraceQL silently returns nothing for an absent attribute.** Unlike PromQL,
-> where a missing label compares equal to `""`, a TraceQL attribute predicate
-> matches only spans that actually carry the attribute — including negated
-> forms such as `!=` and `=~".*"`. So filtering on the wrong span name yields
-> zero rows with no error. `local` has exactly one set-site,
-> `NetworkOPs.cpp:1417`, and it is on **`tx.process`**: an earlier draft paired
-> it with `name="tx.receive"`, which can never match. Check the attribute's
-> owning span in
-> [09 §1.2](./09-data-collection-reference.md) before combining a `name=` and a
-> `span.` predicate.
-
-### 5.8.5 Correlation with Logs
-
-Log↔trace correlation is **implemented** (Phase 8) and needs no Promtail,
-Fluentd or PerfLog change. Two pieces:
-
-1. **The node stamps the IDs.** The journal sink `Logs::format()`
-   (`src/libxrpl/basics/Log.cpp:304-338`, guarded by `XRPL_ENABLE_TELEMETRY`)
-   reads the thread-local OTel context and, when a valid span is active,
-   prefixes the message with `trace_id=<32 hex> span_id=<16 hex>`. It reads
-   the context value directly rather than calling `GetSpan()` to avoid a heap
-   allocation on the (common) no-span path. This is the ordinary `debug.log`
-   stream — PerfLog is not involved, and the `setTraceId` hook described in
-   earlier drafts was never built.
-2. **The collector ingests them.** The `filelog` receiver tails
-   `/var/log/xrpld/*/debug.log` and its `regex_parser` lifts `trace_id` and
-   `span_id` as optional capture groups (§5.5.1). `resource/logs` applies an
-   `upsert` of `service.name=xrpld`, which Loki promotes to the stream label
-   `service_name`, so the canonical selector is **`{service_name="xrpld"}`**.
-   Logs land in Loki via `otlphttp/loki`.
-
-> **Known issue — the collector's `job` upsert is ineffective for stream
-> selection.** `resource/logs` also applies an `upsert` of a `job=xrpld` attribute
-> (`otel-collector-config.yaml:62-70`) with the stated intent that operators
-> could paste `{job="xrpld"}`. That does not work. On OTLP ingest Loki promotes
-> only an **allow-listed** set of resource attributes to indexed stream labels
-> (`service.name`, `service.namespace`, `service.instance.id`,
-> `deployment.environment`, the `k8s.*`/`cloud.*` keys); `job` is not on that
-> list, and this repo ships no Loki config override — `docker-compose.yml:75`
-> starts Loki with the image's built-in `/etc/loki/local-config.yaml`. `job`
-> therefore lands in **structured metadata**, which cannot appear in a stream
-> selector, so `{job="xrpld"}` returns an empty result rather than an error.
-> Corroboration in-repo: `docs/telemetry-runbook.md:2533` states the same
-> ("`service_name="xrpld"` (not `job="xrpld"`)"), and **all 38 Loki queries** in
-> the shipped dashboards (35 panel targets + 3 Loki-backed template variables)
-> select on `service_name` — **zero** use `job`. Either drop the `job`
-> upsert or add `job` to Loki's `distributor.otlp_config.resource_attributes`
-> allow-list via a mounted Loki config; until then, use `service_name`.
-
-Grafana then links the two directions: the Tempo datasource's `tracesToLogs`
-(`filterByTraceID: true`, `tags: []`) jumps trace → logs, and `loki.yaml`'s
-derived fields jump log → trace.
-
-### 5.8.6 Correlation with Insight/OTel System Metrics
-
-To correlate traces with Beast Insight system metrics:
-
-**Step 1: Export Insight metrics to Prometheus**
-
-Beast Insight metrics are exported natively via OTLP to the OTel Collector,
-which exposes them on its Prometheus endpoint (`:8889`) alongside spanmetrics.
-Set `server=otel` in the `[insight]` section of `xrpld.cfg`; no separate StatsD
-exporter or Prometheus scrape job is needed.
-
-`makeCollectorManager()` (`src/xrpld/app/main/CollectorManager.cpp`) reads these
-`[insight]` keys:
-
-| Key                   | Read at      | Effect when `server=otel`                                                                                                          |
-| --------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `server`              | `:35`        | **Live.** `statsd` \| `otel` \| anything else. Selects the collector implementation.                                               |
-| `address`             | `:39`        | StatsD only — the UDP endpoint.                                                                                                    |
-| `prefix`              | `:41`, `:53` | **Inert.** Stored on the OTel collector but `formatName()` prepends nothing (`OTelCollector.cpp:855-866`); only StatsD applies it. |
-| `endpoint`            | `:50`        | **Inert.** Logged for diagnostics (`OTelCollector.cpp:730`), then unused.                                                          |
-| `service_instance_id` | `:58`        | **Inert.** `(void)`-discarded (`OTelCollector.cpp:722`).                                                                           |
-| `service_name`        | `:64`        | **Inert.** `(void)`-discarded (`OTelCollector.cpp:723`).                                                                           |
-
-> **Where the identity and endpoint actually come from.** `OTelCollector`
-> deliberately does **not** own a pipeline: it fetches the Meter from the
-> **global** MeterProvider that `Telemetry::initMetrics()` published
-> (`OTelCollector.cpp:726-745`). So the resource attributes — including
-> `service.instance.id`, which every dashboard filters on — and the exporter
-> URL both come from the **`[telemetry]`** section, not `[insight]`. The four
-> inert keys above are back-compat leftovers from the StatsD-era signature;
-> setting them has no effect. Set `[telemetry] service_instance_id` instead
-> (§5.1.1).
-
-> **`server=otel` is not the default.** `CollectorManager.cpp:72-75` falls through
-> to `NullCollector` for any unrecognised or absent `server` value, so a node
-> with no `[insight]` section emits no metrics at all.
-
-**Step 2: Correlate metrics to traces**
-
-Today this is a **time-range** correlation, not a click-through one: note the
-window from the metric panel, then search Tempo over the same window filtered
-by `service.instance.id`.
-
-> **Exemplars are NOT implemented.** Earlier drafts of this section instructed
-> operators to rely on automatic exemplars, set
-> `exemplarTraceIdDestinations` on the Prometheus datasource, and enable
-> `exemplar: true` on panels. None of that is wired up: the string `exemplar`
-> appears **nowhere** in `src/libxrpl/telemetry/`, `src/xrpld/telemetry/`, or
-> `docker/telemetry/`. Concretely, three things are missing —
->
-> 1. the SDK's exemplar filter is left at its default and no reservoir is
->    configured in `Telemetry::initMetrics()` or `MetricsRegistry`;
-> 2. the collector's `prometheus` exporter has no exemplar settings;
-> 3. `grafana/provisioning/datasources/prometheus.yaml` has no
->    `exemplarTraceIdDestinations` block.
->
-> Note also that the query used as an example, `rpc_duration_seconds_bucket`,
-> does not exist — RPC latency histograms are `span_duration_milliseconds_bucket`
-> (spanmetrics, `unit: ms`) and `rpc_method_us` (native). Wiring exemplars end
-> to end is genuine open work; until it lands, do not document a click-through
-> that operators cannot perform.
-
-**Step 3: Jump the other way instead**
-
-Trace → metrics is available now: the Tempo datasource sets
-`tracesToMetrics.datasourceUid: prometheus` with a ±1h time shift, so the
-span-metric queries it builds resolve against the `span_*` families the
-collector's `spanmetrics` connector produces. Trace → logs and log → trace are
-both live (§5.8.5).
-
-> **Known gap — Service Map is configured but inactive.** The Tempo datasource
-> declares `serviceMap.datasourceUid: prometheus`, and `tempo.yaml:70-76`
-> enables the `service-graphs` metrics-generator processor, but the generator
-> has nowhere to write: its `remote_write` block is **commented out**
-> (`tempo.yaml:53-56`), and `prometheus.yml:6-9` defines a single scrape job
-> against `otel-collector:8889` — it never scrapes or accepts writes from
-> Tempo. `traces_service_graph_request_total` and its siblings are therefore
-> never stored, so the Service Map / Node Graph tab renders empty. The same gap
-> means Tempo's `span-metrics` processor never lands
-> `traces_spanmetrics_*` either (§5.5.1) — every span metric the dashboards use
-> comes from the collector's connector instead. Closing it needs both halves:
-> uncomment `remote_write` in `tempo.yaml` **and** enable
-> `--web.enable-remote-write-receiver` on the Prometheus service (or add a
-> scrape job for Tempo).
-
----
-
-_Previous: [Implementation Strategy](./03-implementation-strategy.md)_ | _Next: [Implementation Phases](./06-implementation-phases.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/07-observability-backends.md

@@ -1,572 +0,0 @@
-# Observability Backend Recommendations
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Implementation Phases](./06-implementation-phases.md) | [Appendix](./08-appendix.md)
-
----
-
-## 7.1 Development/Testing Backends
-
-> **OTLP** = OpenTelemetry Protocol
-
-| Backend    | Pros                                | Cons                   | Use Case            |
-| ---------- | ----------------------------------- | ---------------------- | ------------------- |
-| **Tempo**  | Cost-effective, Grafana integration | Requires Grafana stack | Local dev, CI, Prod |
-| **Zipkin** | Simple, lightweight                 | Basic features         | Quick prototyping   |
-
-### Quick Start with Tempo
-
-```bash
-# Start Tempo with OTLP support.
-# Version pinned to match docker/telemetry/docker-compose.yml:55 — keep the
-# two in step, since Tempo config keys change between minor releases.
-#
-# Only 4317 (OTLP/gRPC) is published: docker/telemetry/tempo.yaml:28-33
-# declares a single distributor receiver, `otlp.protocols.grpc` on
-# 0.0.0.0:4317. There is no `http` protocol block, so nothing listens on 4318
-# and publishing it would give you a port that silently refuses connections.
-# 3200 is Tempo's HTTP API/query port (tempo.yaml:17-18), not an ingest port.
-docker run -d --name tempo \
-    -p 3200:3200 \
-    -p 4317:4317 \
-    grafana/tempo:2.9.4
-```
-
-> Note that xrpld itself exports OTLP/**HTTP** only (§2.2.1), so it cannot send
-> to this container directly — the collector is what bridges HTTP ingest to
-> Tempo's gRPC receiver (`otlp/tempo` → `tempo:4317`). A bare Tempo container is
-> useful for replaying traces from another OTLP/gRPC producer, not as an xrpld
-> endpoint.
-
-> In practice, prefer the full stack —
-> `docker compose -f docker/telemetry/docker-compose.yml up -d` — over a bare
-> Tempo container. Most shipped dashboards query Prometheus span metrics, which
-> need the collector and Prometheus services too. See
-> [05 §5.6](./05-configuration-reference.md).
-
----
-
-## 7.2 Production Backends
-
-> **APM** = Application Performance Monitoring
-
-| Backend           | Pros                                      | Cons                   | Use Case                    |
-| ----------------- | ----------------------------------------- | ---------------------- | --------------------------- |
-| **Grafana Tempo** | Cost-effective, Grafana integration       | Requires Grafana stack | 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
-```
-
-**Reading the diagram:**
-
-- **Budget Constraints? (Yes)**: Leads to open-source options. If you already run Grafana or Elastic, pick the matching backend; otherwise default to Grafana Tempo.
-- **Budget Constraints? (No) → Prefer SaaS?**: If you want a managed service, choose between Datadog (enterprise support) and Honeycomb (developer-focused). If not, fall back to open-source.
-- **Terminal nodes (Tempo / Elastic / Honeycomb / Datadog)**: Each represents a concrete backend choice, all of which feed into the same final step.
-- **Configure Collector**: Regardless of backend, you always finish by configuring the OTel Collector to export to your chosen destination.
-
----
-
-## 7.3 Recommended Production Architecture
-
-> **OTLP** = OpenTelemetry Protocol | **APM** = Application Performance Monitoring | **HA** = High Availability
-
-```mermaid
-flowchart TB
-    subgraph validators["Validator Nodes"]
-        v1[xrpld<br/>Validator 1]
-        v2[xrpld<br/>Validator 2]
-    end
-
-    subgraph stock["Stock Nodes"]
-        s1[xrpld<br/>Stock 1]
-        s2[xrpld<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
-
-    %% Note: simplified single-collector-per-DC topology shown for clarity
-
-    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
-```
-
-**Reading the diagram:**
-
-- **Validator / Stock Nodes**: All xrpld nodes emit trace data via OTLP. Validators and stock nodes are grouped separately because they may reside in different network zones.
-- **Collector Cluster (DC1, DC2)**: Regional collectors receive OTLP from nodes in their datacenter, apply processing (sampling, enrichment), and fan out to multiple backends. Enrichment includes deployment-tier tagging: each collector stamps `deployment.environment` and (as a fallback) `xrpl.network.type` so one Grafana stack can filter data from many collectors by tier.
-- **Storage Backends**: Tempo and Elastic provide queryable trace storage; S3/GCS Archive provides long-term cold storage for compliance or post-incident analysis.
-- **Grafana Dashboards**: The single visualization layer that queries both Tempo and Elastic, giving operators a unified view of all traces.
-- **Data flow direction**: Nodes → Collectors → Storage → Grafana. Each arrow represents a network hop; minimizing collector-to-backend hops reduces latency.
-
-> **Note**: Production deployments should use multiple collector instances behind a load balancer for high availability. The diagram shows a simplified single-collector topology for clarity.
-
----
-
-## 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 xrpld networks:
-
-- One collector cluster per datacenter/region
-- Tail-based sampling at collector level
-- Multiple export destinations for redundancy
-
-### 7.4.2 Sampling Strategy
-
-An earlier version of this section described a three-policy tail sampler (keep
-all errors / keep anything >5s / keep 10% of the rest). **No such sampler
-exists in this repo.** What ships is below.
-
-```mermaid
-flowchart LR
-    subgraph head["Head Sampling (Node) — fixed"]
-        hs["ParentBased(TraceIdRatio 1.0)<br/>samplingRatio is static constexpr<br/>no config key exists<br/>100% of spans exported"]
-    end
-
-    subgraph tail["Tail Sampling (Collector) — opt-in"]
-        base["Base config:<br/>NO tail_sampling processor<br/>100% of traces stored"]
-        cloud["grafanacloud overlay only:<br/>one probabilistic policy<br/>sampling_percentage: 0.5"]
-    end
-
-    head --> tail
-    base --> final["Stored Traces"]
-    cloud --> final
-
-    style head fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style tail fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style hs fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style base fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style cloud fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style final fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **Head Sampling (Node)** — fixed at 100% and genuinely not configurable:
-  `Telemetry.h:234` declares `static constexpr double samplingRatio = 1.0;` and
-  `TelemetryConfig.cpp:139` records that there is nothing to parse. This is
-  intentional: a per-node ratio would let different nodes make divergent
-  keep/drop decisions for the same distributed trace, producing broken/partial
-  traces. The ratio sampler is wrapped in a `ParentBased` sampler so spans
-  inheriting a remote parent honour the upstream decision.
-- **Tail Sampling (Collector)** — the base config
-  (`docker/telemetry/otel-collector-config.yaml`) has **no** `tail_sampling`
-  processor, so the local and CI stacks keep 100% of traces. The only shipped
-  policy lives in `otel-collector-config.grafanacloud.yaml:60-67`, wired into
-  the **`traces/store`** pipeline (`:259-261`) — the overlay has no pipeline
-  named `traces`; it splits the trace stream into `traces/metrics` (unsampled,
-  feeds `spanmetrics`) and `traces/store` (sampled, feeds Tempo and Grafana
-  Cloud). See [05 §5.5.2](./05-configuration-reference.md) for the full overlay
-  delta. The policy is a single `probabilistic` at **0.5%**,
-  `decision_wait: 10s`, `num_traces: 50000`. There are no error or latency
-  carve-outs.
-- **Why 0.5% does not damage the dashboards**: the policy is applied on the
-  trace-storage branch only. The `spanmetrics` connector runs on a separate
-  branch that still sees every span, so `span_calls_total` and
-  `span_duration_milliseconds_*` remain exact. Sampling costs you individual
-  example traces in Tempo, not metric accuracy.
-- **If you want the error/latency policies**: they are a reasonable thing to
-  add, but they must be written — and `decision_wait` sized so a trace's spans
-  have all arrived before the policy evaluates it.
-
-#### Companion guard: `memory_limiter` (recommended, not configured)
-
-Tail sampling bounds what the collector **stores**; it does not bound what the
-collector **buffers**. `tail_sampling` is the opposite of cheap here — it holds
-up to `num_traces` (50 000) traces in memory for `decision_wait` before
-deciding — and the `spanmetrics` connector keeps a live series cache on top of
-that. A production gateway collector should therefore also run a
-[`memory_limiter`](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/memorylimiterprocessor/README.md)
-processor as an OOM guard: it applies backpressure (refusing new data with a
-retryable error, which the node's `sending_queue` will retry) instead of letting
-the process be killed and losing every buffered trace.
-
-> **Not currently configured anywhere in this repo.** Neither
-> `otel-collector-config.yaml` nor
-> `otel-collector-config.grafanacloud.yaml` declares a `memory_limiter`, and
-> neither compose file sets a container memory limit — so today a traffic spike
-> is bounded only by host RAM. This is a recommendation for real deployments,
-> recorded here because [05 §5.5.1](./05-configuration-reference.md) lists
-> `memory_limiter` among the processors deliberately **absent** from the shipped
-> config and that must not be read as "not needed". Placement rules if you add
-> it: it must be the **first** processor in every pipeline (ahead of `batch`),
-> and `limit_mib` must sit below the container/cgroup limit with headroom for
-> the sampling and spanmetrics caches.
-
-### 7.4.3 Data Retention
-
-| Environment                 | Hot Storage | Warm Storage | Cold Archive | Source                                                       |
-| --------------------------- | ----------- | ------------ | ------------ | ------------------------------------------------------------ |
-| Development (local stack)   | **1 hour**  | N/A          | N/A          | `tempo.yaml:40` — `compactor.compaction.block_retention: 1h` |
-| Staging (recommendation)    | 7 days      | N/A          | N/A          | Not configured in this repo                                  |
-| Production (recommendation) | 7 days      | 30 days      | many years   | Not configured in this repo                                  |
-
-> **The local stack keeps traces for 1 hour, not 24.** `block_retention: 1h`
-> is deliberate — it bounds disk for a long-running dev node — but it means a
-> trace you found this morning is gone by lunchtime. Raise
-> `block_retention` in `docker/telemetry/tempo.yaml` before starting any
-> investigation that needs to span a working day. The staging and production
-> rows are recommendations only; nothing in this repo provisions them.
-
----
-
-## 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 Dashboards and Alerts
-
-> **Superseded.** This section was written in Phase 1a, before any dashboard
-> shipped, and described three hypothetical boards (`xrpld-consensus-health`,
-> `xrpld-node-overview`, `xrpld-unified`) and three TraceQL alert rules in a
-> group called `xrpld-tracing-alerts`. **None of those uids or rule names exist
-> anywhere in the repo.** What actually ships is 15 dashboards and 13 alert
-> rules, and both are Prometheus-first rather than TraceQL-first. The
-> authoritative references are:
->
-> | For                                              | See                                                                                                       |
-> | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-> | Dashboard and panel inventory, per-panel queries | [09-data-collection-reference.md](./09-data-collection-reference.md)                                      |
-> | Alert catalogue, thresholds and response steps   | `docs/telemetry-runbook.md`                                                                               |
-> | Files on disk                                    | `docker/telemetry/grafana/dashboards/*.json`, `docker/telemetry/grafana/provisioning/alerting/rules.yaml` |
->
-> The rest of this section records only the facts a reader needs so as not to
-> chase the removed names.
-
-### 7.6.1 Shipped Dashboards
-
-15 JSON dashboards are provisioned into Grafana folder `xrpld`. The uids are
-bare — there is no `xrpld-` prefix:
-
-`consensus-health`, `fee-market`, `job-queue`, `ledger-data-sync`,
-`ledger-operations`, `log-derived-insights`, `network-traffic`, `node-health`,
-`overlay-traffic-detail`, `peer-network`, `peer-quality`, `rpc-pathfinding`,
-`rpc-performance`, `transaction-overview`, `validator-health`.
-
-> **Panel-count convention** (shared with [05 §5.8.3](./05-configuration-reference.md)):
-> counts are of **data panels only**. `type: "row"` collapsible headers are
-> excluded because a row carries no query, so a board's raw `panels` array is
-> longer than its stated count.
-
-`consensus-health.json` is a useful calibration for how far this section drifted:
-where the removed text described "four TraceQL panels", the real board carries **22
-data panels** in 4 rows (26 `panels` array entries) — 19 Prometheus targets
-against `${DS_PROMETHEUS}` and 9 TraceQL targets against `${DS_TEMPO}`. Tempo is
-used for trace _drill-down_; the time series come from span metrics.
-
-### 7.6.2 Shipped Alert Rules
-
-`docker/telemetry/grafana/provisioning/alerting/rules.yaml` provisions **13
-rules in 5 groups**, all in folder `xrpld`, all `interval: 1m`, and all
-**PromQL** — there are zero TraceQL alert rules.
-
-| Group              | Rules                                                                       |
-| ------------------ | --------------------------------------------------------------------------- |
-| `xrpld-consensus`  | `LedgerHistoryMismatch`, `LedgerCloseStalled`, `ValidatedLedgerStale`       |
-| `xrpld-validator`  | `ValidationsMissed`, `ValidationsNotChecked`                                |
-| `xrpld-jobqueue`   | `JobQueueTxOverflow`, `JobQueueLatencyHigh`, `NodeStoreIOLatencyHigh`       |
-| `xrpld-node-state` | `NodeStateFlapping`, `NodeNotFull`                                          |
-| `xrpld-overlay`    | `ManifestJobQueueConvoy`, `ManifestFloodInbound`, `PeerResourceDisconnects` |
-
-> Two placements are worth noting because they are not what the rule name
-> suggests. `ValidatedLedgerStale` is grouped under `xrpld-consensus`, not
-> `xrpld-validator` — it fires on any node whose validated-ledger sequence stops
-> advancing, which is a chain-progress symptom rather than a validator-identity
-> one. `NodeStoreIOLatencyHigh` is grouped under `xrpld-jobqueue`, not
-> `xrpld-node-state` — slow NodeStore I/O manifests first as job-queue backlog,
-> so grouping it there keeps the cause and its effect in one notification.
-
-Thresholds, measured baselines and response procedures are in the runbook's
-alert catalogue, not here.
-
-### 7.6.3 Writing New Rules: the metric name
-
-If you add a span-metric alert, the metric is **`span_calls_total`**. This stack
-sets the `spanmetrics` connector's `namespace: "span"`
-(`otel-collector-config.yaml:114`); the connector's own default namespace is
-**empty**, so without that setting the names would be the bare `calls_total` /
-`duration_milliseconds_*`. 7 of the 15 dashboards already query the `span_`
-names. Durations are likewise `span_duration_milliseconds_bucket`.
-
-> **`traces_spanmetrics_*` is a different producer, not the connector's
-> default.** That family is emitted by **Tempo's** `metrics_generator`
-> `span-metrics` processor (`tempo.yaml:70-76`), which is a separate
-> implementation from the collector connector. It does not exist in this stack
-> either: the generator's `remote_write` is commented out (`tempo.yaml:53-56`)
-> and `prometheus.yml:6-9` scrapes only `otel-collector:8889`, so nothing stores
-> what Tempo generates. Do not write a rule against `traces_spanmetrics_*` and
-> do not describe `namespace: "span"` as overriding it.
-
-An RPC error-rate rule, written against the real metric name, looks like this.
-Note that error _rate_ is a ratio, so it must divide the error-span rate by the
-total-span rate — a bare rate returns calls/second and would fire on traffic
-volume alone:
-
-```
-sum(rate(span_calls_total{service_name="xrpld", span_name=~"rpc.command.*", status_code="STATUS_CODE_ERROR"}[5m]))
-/
-sum(rate(span_calls_total{service_name="xrpld", span_name=~"rpc.command.*"}[5m]))
-> 0.05
-```
-
-> **Prefer PromQL over TraceQL for alerting.** TraceQL aggregates
-> (`avg(duration)`, `rate()`) need Tempo 2.3+ with TraceQL metrics enabled, are
-> slower, and are distorted by any tail sampling in the path (§7.4.2). Span
-> metrics are computed pre-sampling and cost nothing extra to query. That is
-> why all 13 shipped rules are PromQL.
-
----
-
-## 7.7 PerfLog and Insight Correlation
-
-> **OTLP** = OpenTelemetry Protocol
-
-How to correlate OpenTelemetry traces with existing xrpld observability.
-
-### 7.7.1 Correlation Architecture
-
-There is **one** collection agent, not three. Earlier drafts of this diagram
-routed logs through "Promtail/Fluentd" and metrics through a "StatsD Exporter";
-neither exists in this stack. Logs are read by the OTel Collector's own
-`filelog` receiver, and `beast::insight` metrics arrive at the same collector
-over OTLP (`[insight] server=otel`). The single-agent shape is the point: one
-process, one config file, one place to add redaction or tier tagging.
-
-```mermaid
-flowchart TB
-    subgraph xrpld["xrpld Node"]
-        otel["OpenTelemetry Spans"]
-        journal["Journal debug.log<br/>trace_id= span_id= prefix<br/>(Log.cpp:304-338)"]
-        insight["Beast Insight + XRPL_METRIC_*<br/>native OTLP metrics"]
-    end
-
-    otelc["OTel Collector<br/>receivers: otlp, filelog<br/>connector: spanmetrics<br/>3 pipelines"]
-
-    subgraph storage["Storage"]
-        tempo[("Tempo")]
-        loki[("Loki")]
-        prom[("Prometheus")]
-    end
-
-    dashboards["Grafana<br/>Tempo to Loki via tracesToLogs<br/>Loki to Tempo via derived fields"]
-
-    otel -->|"OTLP/HTTP :4318"| otelc
-    journal -->|"filelog tails<br/>/var/log/xrpld"| otelc
-    insight -->|"OTLP/HTTP :4318"| otelc
-
-    otelc -->|"otlp/tempo"| tempo
-    otelc -->|"otlphttp/loki"| loki
-    otelc -->|"prometheus :8889"| prom
-
-    tempo --> dashboards
-    loki --> dashboards
-    prom --> dashboards
-
-    style xrpld fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style storage fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style otel fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style journal fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style insight fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style otelc fill:#bf360c,stroke:#8c2809,color:#ffffff
-    style tempo fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style loki fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style prom fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style dashboards fill:#4a148c,stroke:#2e0d57,color:#ffffff
-```
-
-**Reading the diagram:**
-
-- **xrpld Node (three signals, one transport)**: spans and metrics both leave over OTLP/HTTP on port 4318. Logs do not leave the node at all — the node just writes `debug.log`, and the journal sink prefixes `trace_id=`/`span_id=` whenever a span is active (`Log.cpp:304-338`).
-- **OTel Collector (single agent)**: an `otlp` receiver takes spans and metrics; a `filelog` receiver tails `/var/log/xrpld/*/debug.log` and regex-parses the trace/span IDs out of each line. A `spanmetrics` connector derives RED metrics from the trace stream and feeds them into the metrics pipeline. Three pipelines, three exporters — see [05 §5.5.1](./05-configuration-reference.md).
-- **PerfLog is not in this picture.** It still writes `perf.log`, but nothing collects it and it carries no trace ID; the `setTraceId` hook once planned for it was never built ([02 §2.6.5](./02-design-decisions.md)).
-- **StatsD is not in this picture either.** It remains a supported `[insight] server=` choice, but selecting it takes metrics _out_ of this pipeline and requires a StatsD receiver you would have to add yourself — the compose file's StatsD port mapping is commented out.
-- **Grafana**: correlation is bidirectional and configured in the datasources, not in a bespoke panel — Tempo's `tracesToLogs` (`filterByTraceID: true`) jumps trace → logs, and `loki.yaml`'s derived fields jump log → trace.
-
-### 7.7.2 Correlation Fields
-
-| Source          | Field                 | Link To | Status                                                                                                                                                                                                                                                            |
-| --------------- | --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Trace**       | `trace_id`            | Logs    | **Live.** Tempo `tracesToLogs`, `filterByTraceID: true`                                                                                                                                                                                                           |
-| **Trace**       | `tx_hash`             | —       | Live as a span attribute for search; **not** used as a cross-signal join key (`tags: []`)                                                                                                                                                                         |
-| **Trace**       | `ledger_seq`          | —       | Live as a span attribute; not a join key                                                                                                                                                                                                                          |
-| **Journal log** | `trace_id`, `span_id` | Traces  | **Live.** Emitted by `Log.cpp:304-338` into `debug.log`, parsed by the collector's `filelog` receiver, jumped via `loki.yaml` derived fields                                                                                                                      |
-| **PerfLog**     | `trace_id`            | Traces  | **Not implemented.** PerfLog output has no trace ID; the planned `setTraceId` hook was never built. Use the journal log instead                                                                                                                                   |
-| **Insight**     | `exemplar.trace_id`   | Traces  | **Not implemented.** No exemplar configuration exists anywhere in the code or collector config — no `exemplar_filter` on the SDK side, no `exemplarTraceIdDestinations` on the Prometheus datasource. Metric spike → trace jumps must be done by time range today |
-
-### 7.7.3 Example: Debugging a Slow Transaction
-
-**Step 1: Find the trace**
-
-```
-# In Grafana Explore with Tempo
-{resource.service.name="xrpld" && span.tx_hash="ABC123..."}
-```
-
-**Step 2: Get the trace_id from the trace view**
-
-```
-Trace ID: 4bf92f3577b34da6a3ce929d0e0e4736
-```
-
-**Step 3: Find related log lines**
-
-```
-# In Grafana Explore with Loki. `service_name` is the promoted stream label;
-# do NOT use {job="xrpld"} — see the note below.
-{service_name="xrpld"} |= "4bf92f3577b34da6a3ce929d0e0e4736"
-```
-
-These are journal (`debug.log`) lines, not PerfLog lines — see §7.7.2.
-
-> **Known issue — `{job="xrpld"}` does not select anything.** The collector's
-> `resource/logs` processor does upsert a `job=xrpld` resource attribute
-> (`otel-collector-config.yaml:62-70`), explicitly so that operators could paste
-> `{job="xrpld"}`. Loki does not cooperate: on OTLP ingest it promotes only an
-> **allow-listed** set of resource attributes to indexed stream labels
-> (`service.name`, `service.namespace`, `service.instance.id`,
-> `deployment.environment`, `k8s.*`, `cloud.*`), and `job` is not on it. This
-> repo mounts no Loki config override (`docker-compose.yml:75` uses the image's
-> built-in `local-config.yaml`), so `job` lands in **structured metadata** —
-> queryable only with a `|` filter after a selector, never as the selector
-> itself. A `{job="xrpld"}` query returns empty with no error, which is why this
-> is easy to miss. `docs/telemetry-runbook.md:2533` says the same, and all 38
-> Loki queries in the shipped dashboards (35 panel targets + 3 template
-> variables) select on `service_name` — zero use `job`. Fix options:
-> drop the ineffective `job` upsert, or mount a Loki config adding `job` to
-> `distributor.otlp_config.resource_attributes`.
-
-**Step 4: Check metrics for the time window**
-
-```
-# In Grafana with Prometheus. Span-derived RED metrics for the transaction
-# pipeline (namespace "span" — see 7.6.3):
-sum(rate(span_calls_total{span_name="tx.process"}[1m])) by (service_instance_id)
-
-# Error share of the same pipeline. Note !~"tesSUCCESS|" — NOT
-# !="tesSUCCESS" — so spans that carry no ter_result are excluded:
-sum(rate(span_calls_total{span_name="tx.process", ter_result!~"tesSUCCESS|"}[5m]))
-/
-sum(rate(span_calls_total{span_name="tx.process"}[5m]))
-```
-
-> **Why the regex form.** An absent Prometheus label is indistinguishable from
-> the empty string, and `tx.process` can end **without** a `ter_result`: the span
-> is opened at `NetworkOPs.cpp:1416`, but `processTransaction()` returns early
-> when `preProcessTransaction()` rejects the transaction (`:1437-1438`), and
-> `doTransactionAsync()` returns early when the transaction is already applying
-> (`:1461-1462`) — both before the only setter, at `:1674`. Those series arrive
-> with `ter_result=""`, which `!="tesSUCCESS"` happily counts as a failure and
-> inflates the ratio. `!~"tesSUCCESS|"` excludes the empty value via the trailing
-> `|` alternative. This is the form `docs/telemetry-runbook.md:1198` and the
-> `transaction-overview.json` stage-failure panels already use; apply it to any
-> new `ter_result` predicate.
-
-> Earlier drafts used `rate(xrpld_tx_applied_total[1m])` and
-> `rate(xrpld_tx_received_total[5m])`. **Neither metric exists** — there is no
-> `xrpld_`-prefixed metric family at all, because `OTelCollector::formatName()`
-> deliberately prepends no prefix (`OTelCollector.cpp:855-866`); the OTel
-> resource `service.name` identifies the service instead. Use the `span_*`
-> families above (verified in `transaction-overview.json` and
-> `rpc-performance.json`) or the native `XRPL_METRIC_*` instrument names listed
-> in [09-data-collection-reference.md](./09-data-collection-reference.md).
-
-### 7.7.4 Unified Dashboard
-
-> **Superseded.** No `xrpld-unified` dashboard exists. The single-pane view it
-> described is instead delivered by two things that did ship: the
-> **`log-derived-insights`** dashboard (31 data panels in 10 rows, all
-> Loki-backed — 41 `panels` array entries; see the counting convention in
-> §7.6.1) plus the
-> bidirectional datasource links (Tempo `tracesToLogs` → Loki, `loki.yaml`
-> derived fields → Tempo), which let you cross signals from _any_ board rather
-> than only from one dedicated dashboard.
->
-> The correlation fields those links rely on — and which of them are actually
-> implemented — are in §7.7.2. For the full board inventory see
-> [09-data-collection-reference.md](./09-data-collection-reference.md).
-
----
-
-_Previous: [Implementation Phases](./06-implementation-phases.md)_ | _Next: [Appendix](./08-appendix.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/08-appendix.md

@@ -1,233 +0,0 @@
-# Appendix
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Observability Backends](./07-observability-backends.md)
-
----
-
-## 8.1 Glossary
-
-> **OTLP** = OpenTelemetry Protocol | **TxQ** = Transaction Queue
-
-| 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                           |
-
-### xrpld-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 xrpld                  |
-| **Beast Insight** | Existing metrics framework in xrpld                           |
-| **PathFinding**   | Payment path computation engine for cross-currency payments   |
-| **TxQ**           | Transaction queue managing fee-based prioritization           |
-| **LoadManager**   | Dynamic fee escalation based on network load                  |
-| **SHAMap**        | SHA-256 hash-based map (Merkle trie variant) for ledger state |
-
-### Phase 9–11 Terms
-
-| Term                        | Definition                                                                |
-| --------------------------- | ------------------------------------------------------------------------- |
-| **MetricsRegistry**         | Centralized class for OTel async gauge registrations (Phase 9)            |
-| **ObservableGauge**         | OTel Metrics SDK async instrument polled via callback at fixed intervals  |
-| **PeriodicMetricReader**    | OTel SDK component that invokes gauge callbacks at configurable intervals |
-| **CountedObject**           | xrpld template that tracks live instance counts via atomic counters       |
-| **TxQ**                     | Transaction queue managing fee escalation and ordering                    |
-| **Load Factor**             | Combined multiplier affecting transaction cost (local, cluster, network)  |
-| **OTel Collector Receiver** | Custom Go plugin that polls xrpld RPC and emits OTel metrics (Phase 11)   |
-
----
-
-## 8.2 Span Hierarchy Visualization
-
-The authoritative span-flow diagrams — a master overview plus per-stage
-flowcharts (ingress, the shared apply pipeline, the consensus round, ledger
-finalize, and the pathfinding / ledger-acquire side flows) — live in the operator
-runbook. They map every span onto the **real xrpld control flow and XRPL protocol
-order** (verified against code and `docs/consensus.md`, with file:line evidence),
-label every node and branch with the span that represents that state or
-transition, and call out where the OpenTelemetry span parent links diverge from
-that flow.
-
-> **See**: [docs/telemetry-runbook.md § Protocol Span Flow](../docs/telemetry-runbook.md#protocol-span-flow).
-
-The full span inventory (names, attributes, parents as instrumented) is in
-[09-data-collection-reference.md §1](./09-data-collection-reference.md#1-opentelemetry-spans).
-
----
-
-## 8.3 References
-
-> **OTLP** = OpenTelemetry Protocol
-
-### 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/)
-
-### xrpld Resources
-
-8. [xrpld Source Code](https://github.com/XRPLF/rippled)
-9. [XRP Ledger Documentation](https://xrpl.org/docs/)
-10. [xrpld Overlay README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/overlay/README.md)
-11. [xrpld RPC README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/rpc/README.md)
-12. [xrpld Consensus README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/app/consensus/README.md)
-
----
-
-## 8.4 Version History
-
-| Version | Date       | Author | Changes                                                        |
-| ------- | ---------- | ------ | -------------------------------------------------------------- |
-| 1.0     | 2026-02-12 | -      | Initial implementation plan                                    |
-| 1.1     | 2026-02-13 | -      | Refactored into modular documents                              |
-| 1.2     | 2026-03-09 | -      | Added Phases 9–11 (future enhancement plans)                   |
-| 1.3     | 2026-03-24 | -      | Review fixes: accuracy corrections, cross-document consistency |
-
----
-
-## 8.5 Document Index
-
-### Plan Documents
-
-| Document                                                             | Description                                        |
-| -------------------------------------------------------------------- | -------------------------------------------------- |
-| [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)                       | Master overview and executive summary              |
-| [00-tracing-fundamentals.md](./00-tracing-fundamentals.md)           | Distributed tracing concepts and OTel primer       |
-| [01-architecture-analysis.md](./01-architecture-analysis.md)         | xrpld architecture and trace points                |
-| [02-design-decisions.md](./02-design-decisions.md)                   | SDK selection, exporters, span conventions         |
-| [03-implementation-strategy.md](./03-implementation-strategy.md)     | Directory structure, performance analysis          |
-| [05-configuration-reference.md](./05-configuration-reference.md)     | xrpld config, CMake, Collector configs             |
-| [06-implementation-phases.md](./06-implementation-phases.md)         | Timeline, tasks, risks, success metrics            |
-| [07-observability-backends.md](./07-observability-backends.md)       | Backend selection and architecture                 |
-| [08-appendix.md](./08-appendix.md)                                   | Glossary, references, version history              |
-| [secure-OTel.md](./secure-OTel.md)                                   | Threat model and hardening (mTLS, peer validation) |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Span/metric/dashboard inventory                    |
-
-### Task Lists
-
-| Document                                                                   | Description                                    |
-| -------------------------------------------------------------------------- | ---------------------------------------------- |
-| [Phase2_taskList.md](./Phase2_taskList.md)                                 | RPC layer trace instrumentation                |
-| [Phase3_taskList.md](./Phase3_taskList.md)                                 | Peer overlay & consensus tracing               |
-| [Phase4_taskList.md](./Phase4_taskList.md)                                 | Transaction lifecycle tracing                  |
-| [Phase5_taskList.md](./Phase5_taskList.md)                                 | Ledger processing & advanced tracing           |
-| [Phase5_IntegrationTest_taskList.md](./Phase5_IntegrationTest_taskList.md) | Observability stack integration tests          |
-| [Phase7_taskList.md](./Phase7_taskList.md)                                 | Native OTel metrics migration                  |
-| [Phase8_taskList.md](./Phase8_taskList.md)                                 | Log-trace correlation                          |
-| [Phase9_taskList.md](./Phase9_taskList.md)                                 | Internal metric instrumentation gap fill       |
-| [Phase10_taskList.md](./Phase10_taskList.md)                               | Synthetic workload generation & validation     |
-| [Phase11_taskList.md](./Phase11_taskList.md)                               | Third-party data collection pipelines (future) |
-
-> **Only Phase 11 is still "future".** Phase 9 ships on
-> `pratik/otel-phase9-metric-gap-fill` (18 task entries, 9.1–9.17 plus 9.7a) and
-> Phase 10 on `pratik/otel-phase10-workload-validation` (7 tasks). Their task
-> lists are present on every branch from those points forward, so a reader on a
-> later branch sees plans that are already implemented, not proposals. Phase 11
-> (13 tasks) has no implementation branch.
-
-> **Note**: Phases 1 and 6 do not have separate task list files. Phase 1 tasks are documented in [06-implementation-phases.md §6.2](./06-implementation-phases.md). Phase 6 tasks are documented in [06-implementation-phases.md §6.7](./06-implementation-phases.md).
-
----
-
-## 8.6 Phase 9–11 Cross-Reference Guide
-
-This guide maps Phase 9–11 content to its location across the documentation.
-
-### Phase 9: Internal Metric Instrumentation Gap Fill
-
-| Content                          | Location                                                                                                                         |
-| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| Plan & architecture              | [06-implementation-phases.md §6.8.2](./06-implementation-phases.md)                                                              |
-| Task list (18 entries, 9.1–9.17) | [Phase9_taskList.md](./Phase9_taskList.md)                                                                                       |
-| Metric definitions               | [09-data-collection-reference.md §5b](./09-data-collection-reference.md)                                                         |
-| New class: `MetricsRegistry`     | `src/xrpld/telemetry/MetricsRegistry.h/.cpp` — **shipped**                                                                       |
-| New dashboards (4)               | `fee-market`, `job-queue`, `peer-quality`, `validator-health` — **shipped**                                                      |
-| Updated dashboards (2)           | `node-health`, `rpc-performance`                                                                                                 |
-| Provisioned alert rules          | `docker/telemetry/grafana/provisioning/alerting/rules.yaml` — 13 rules in 5 groups ([07 §7.6.2](./07-observability-backends.md)) |
-
-> **Task numbering**: `Phase9_taskList.md` carries 18 `## Task 9.x` headings —
-> 9.1 through 9.17 plus the inserted 9.7a (`push_metrics.py` parity). The "10
-> tasks" figure in earlier revisions predates 9.7a and 9.11–9.17. Tasks 9.8 and
-> 9.11–9.13 together produce the four new dashboards; Task 9.17 (peer span
-> coverage) is explicitly **deferred to Phase 11**.
-
-**Metric categories**: NodeStore I/O, Cache Hit Rates, TxQ, PerfLog Per-RPC, PerfLog Per-Job, Counted Objects, Fee Escalation & Load Factors.
-
-### Phase 10: Synthetic Workload Generation & Telemetry Validation
-
-| Content              | Location                                                                 |
-| -------------------- | ------------------------------------------------------------------------ |
-| Plan & architecture  | [06-implementation-phases.md §6.8.3](./06-implementation-phases.md)      |
-| Task list (7 tasks)  | [Phase10_taskList.md](./Phase10_taskList.md)                             |
-| Branch               | `pratik/otel-phase10-workload-validation`                                |
-| Validation inventory | [09-data-collection-reference.md §5c](./09-data-collection-reference.md) |
-| Test harness         | `docker/telemetry/docker-compose.workload.yaml` (phase-10 branch)        |
-| CI workflow          | `.github/workflows/telemetry-validation.yml` (phase-10 branch)           |
-
-**Validates** (Phase-10 harness inventory): **40** span types, **67** unique
-required span attributes, **36** metric entries, **14** dashboards, log-trace
-correlation.
-
-> **These are the harness manifests' counts, and two of them lag the code.** The
-> manifests (`docker/telemetry/workload/expected_spans.json`,
-> `expected_metrics.json`) live only on the phase-10 branch. `expected_spans.json`
-> holds 40 span entries against the **41** span-name families the code emits
-> (`rpc.ws_upgrade` has no entry), and its own `total_unique_attributes: 58` field
-> is stale against the 67 attributes its per-span `required_attributes` lists
-> actually name. `expected_metrics.json` asserts 14 dashboard uids against the
-> **15** dashboard JSONs in `docker/telemetry/grafana/dashboards/`;
-> `log-derived-insights` is the unasserted one. The full emitted inventory is in
-> [09-data-collection-reference.md §1.1](./09-data-collection-reference.md#11-complete-span-inventory-41-spans)
-> and [§5c](./09-data-collection-reference.md#validated-telemetry-inventory).
-
-### Phase 11: Third-Party Data Collection Pipelines
-
-| Content                           | Location                                                                 |
-| --------------------------------- | ------------------------------------------------------------------------ |
-| Plan & architecture               | [06-implementation-phases.md §6.8.4](./06-implementation-phases.md)      |
-| Task list (13 tasks)              | [Phase11_taskList.md](./Phase11_taskList.md)                             |
-| External metric definitions (~30) | [09-data-collection-reference.md §5d](./09-data-collection-reference.md) |
-| Custom OTel Collector receiver    | `docker/telemetry/otel-rippled-receiver/` (planned)                      |
-| Prometheus alerting rules (11)    | [09-data-collection-reference.md §5d](./09-data-collection-reference.md) |
-| New dashboards (4)                | Validator Health, Network Topology, Fee Market (External), DEX & AMM     |
-
-> **Two of those names now collide with shipped Phase-9 boards.** Phase 9
-> already ships `validator-health` and `fee-market`, both built from the node's
-> **own** telemetry. The Phase-11 entries are the third-party-data variants
-> (network-wide validator agreement, external fee/DEX feeds via the custom
-> receiver). They need distinct uids, or they will overwrite the Phase-9 boards
-> on provisioning.
-
-**Consumer categories**: Exchanges, Payment Processors, DeFi/AMM, NFT Marketplaces, Analytics Providers, Wallets, Compliance, Academic Researchers, Institutional Custody, CBDC Bridge Operators.
-
----
-
-_Previous: [Observability Backends](./07-observability-backends.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_

OpenTelemetryPlan/OpenTelemetryPlan.md

@@ -1,251 +0,0 @@
-# [OpenTelemetry](00-tracing-fundamentals.md) Distributed Tracing Implementation Plan for xrpld
-
-## Executive Summary
-
-> **OTLP** = OpenTelemetry Protocol
-
-This document provides a comprehensive implementation plan for integrating OpenTelemetry distributed tracing into the xrpld XRP Ledger node software. The plan addresses the unique challenges of a decentralized peer-to-peer system where trace context must propagate across network boundaries between independent nodes.
-
-### Key Benefits
-
-- **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        | <10 MB     | SDK statics + batch buffer + worker thread stack |
-| 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 fundamentals["Fundamentals"]
-        fund["00-tracing-fundamentals.md"]
-    end
-
-    subgraph analysis["Analysis & Design"]
-        arch["01-architecture-analysis.md"]
-        design["02-design-decisions.md"]
-    end
-
-    subgraph impl["Implementation"]
-        strategy["03-implementation-strategy.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"]
-        secure["secure-OTel.md"]
-        dataref["09-data-collection-reference.md"]
-    end
-
-    overview --> fundamentals
-    overview --> analysis
-    overview --> impl
-    overview --> deploy
-
-    fund --> arch
-    arch --> design
-    design --> strategy
-    strategy --> config
-    config --> phases
-    phases --> backends
-    backends --> appendix
-    backends --> secure
-    appendix --> dataref
-
-    style overview fill:#1b5e20,stroke:#0d3d14,color:#fff,stroke-width:2px
-    style fundamentals fill:#00695c,stroke:#004d40,color:#fff
-    style fund fill:#00695c,stroke:#004d40,color:#fff
-    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 config fill:#bf360c,stroke:#8c2809,color:#fff
-    style phases fill:#4a148c,stroke:#2e0d57,color:#fff
-    style backends fill:#4a148c,stroke:#2e0d57,color:#fff
-    style appendix fill:#4a148c,stroke:#2e0d57,color:#fff
-    style secure fill:#4a148c,stroke:#2e0d57,color:#fff
-    style dataref fill:#4a148c,stroke:#2e0d57,color:#fff
-```
-
-</div>
-
----
-
-## Table of Contents
-
-| Section | Document                                                       | Description                                                            |
-| ------- | -------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| **0**   | [Tracing Fundamentals](./00-tracing-fundamentals.md)           | Distributed tracing concepts, span relationships, context propagation  |
-| **1**   | [Architecture Analysis](./01-architecture-analysis.md)         | xrpld component analysis, trace points, instrumentation priorities     |
-| **2**   | [Design Decisions](./02-design-decisions.md)                   | SDK selection, exporters, span naming, attributes, context propagation |
-| **3**   | [Implementation Strategy](./03-implementation-strategy.md)     | Directory structure, key principles, performance optimization          |
-| **5**   | [Configuration Reference](./05-configuration-reference.md)     | xrpld config, CMake integration, Collector configurations              |
-| **6**   | [Implementation Phases](./06-implementation-phases.md)         | 11-phase timeline, tasks, risks, success metrics                       |
-| **7**   | [Observability Backends](./07-observability-backends.md)       | Backend selection guide and production architecture                    |
-| **8**   | [Appendix](./08-appendix.md)                                   | Glossary, references, version history                                  |
-| **9**   | [Data Collection Reference](./09-data-collection-reference.md) | Complete inventory of spans, attributes, metrics, and dashboards       |
-| **Sec** | [Securing the OTel Pipeline](./secure-OTel.md)                 | Threat model and hardening (mTLS, peer trace-context validation)       |
-
-> Note there is no document 4: `04-code-samples.md` was removed during the
-> rollout, and the numbering was left as-is rather than renumbering every
-> cross-reference in the chain.
-
----
-
-## 0. Tracing Fundamentals
-
-This document introduces distributed tracing concepts for readers unfamiliar with the domain. It covers what traces and spans are, how parent-child and follows-from relationships model causality, how context propagates across service boundaries, and how sampling controls data volume. It also maps these concepts to xrpld-specific scenarios like transaction relay and consensus.
-
-➡️ **[Read Tracing Fundamentals](./00-tracing-fundamentals.md)**
-
----
-
-## 1. Architecture Analysis
-
-> **WS** = WebSocket | **TxQ** = Transaction Queue
-
-The xrpld node consists of several key components that require instrumentation for comprehensive distributed tracing. The main areas include the RPC server (HTTP/WebSocket), Overlay P2P network, Consensus mechanism (RCLConsensus), JobQueue for async task execution, PathFinding, Transaction Queue (TxQ), fee escalation (LoadManager), ledger acquisition, validator management, and existing observability infrastructure (PerfLog, Insight/StatsD, Journal logging).
-
-Key trace points span across transaction submission via RPC, peer-to-peer message propagation, consensus round execution, ledger building, path computation, transaction queue behavior, fee escalation, and validator health. The implementation prioritizes high-value, low-risk components first: RPC handlers provide immediate value with minimal risk, while consensus tracing requires careful implementation to avoid timing impacts.
-
-➡️ **[Read full Architecture Analysis](./01-architecture-analysis.md)**
-
----
-
-## 2. Design Decisions
-
-> **OTLP** = OpenTelemetry Protocol | **CNCF** = Cloud Native Computing Foundation
-
-The OpenTelemetry C++ SDK is selected for its CNCF backing, active development, and native performance characteristics. Traces are exported via OTLP/HTTP to an OpenTelemetry Collector, which provides flexible routing and sampling. OTLP/gRPC is planned future work (see design decisions §2.2.2).
-
-Span naming follows a hierarchical `<component>.<operation>` convention (e.g., `rpc.command.server_info`, `tx.process`, `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). Account addresses are hashed **unconditionally** by the SDK helper and hashed again at the collector; there is no redaction config key and therefore no insecure-by-default state. Trace volume is _not_ reduced on the node (head sampling is fixed at 100%); reduction, where wanted, is a collector-side tail-sampling decision. Node operators control which subsystems are traced via the `[telemetry]` per-component toggles.
-
-➡️ **[Read full Design Decisions](./02-design-decisions.md)**
-
----
-
-## 3. Implementation Strategy
-
-The telemetry code is organized under `include/xrpl/telemetry/` for headers, `src/libxrpl/telemetry/` for implementation, and `src/xrpld/telemetry/` for the native-metrics module added in Phases 7 and 9. Key principles include RAII-based span management via `SpanGuard` (with `discard()` for dropping unwanted spans), a `FilteringSpanProcessor` that intercepts `OnEnd()` to prevent discarded spans from entering the export pipeline, conditional compilation behind the `XRPL_ENABLE_TELEMETRY` compile definition (set by the CMake `telemetry` option, which defaults to **ON** — build it out with `-Dtelemetry=OFF`), and minimal runtime overhead through batch processing.
-
-Performance optimization strategies include head sampling fixed at 100% (intentionally not configurable, so trace keep/drop decisions stay coherent across nodes), optional tail-based sampling at the collector to reduce stored volume (not enabled in the base stack — the only shipped policy is a 0.5% probabilistic one in the Grafana Cloud overlay), batch export to reduce network overhead, and conditional instrumentation that compiles to no-ops when disabled.
-
-➡️ **[Read full Implementation Strategy](./03-implementation-strategy.md)**
-
----
-
-## 5. Configuration Reference
-
-> **OTLP** = OpenTelemetry Protocol | **APM** = Application Performance Monitoring
-
-Configuration is handled through the `[telemetry]` section in `xrpld.cfg` with options for enabling/disabling, TLS/mTLS, batch tuning, and component-level filtering. Exporter selection is _not_ configurable — OTLP/HTTP is the only transport. Head sampling is fixed at 1.0 (not operator-configurable); volume reduction is done by tail sampling in the collector. CMake integration uses the `telemetry` option (default **ON**) for compile-time control.
-
-Endpoints are spread across **three** keys in two sections, not one "traces and metrics" pair:
-
-| Signal                                               | Key                            | Default                            | Source                      |
-| ---------------------------------------------------- | ------------------------------ | ---------------------------------- | --------------------------- |
-| Traces                                               | `[telemetry] endpoint`         | `http://localhost:4318/v1/traces`  | `TelemetryConfig.cpp:36,61` |
-| Native metrics (`XRPL_METRIC_*` / `MetricsRegistry`) | `[telemetry] metrics_endpoint` | `http://localhost:4318/v1/metrics` | `Application.cpp:1670`      |
-| `beast::insight` metrics (`server=otel`)             | `[insight] endpoint`           | `http://localhost:4318/v1/metrics` | `CollectorManager.cpp:50`   |
-
-`[telemetry]` itself has exactly **one** `endpoint` key, and it is traces-only.
-
-The repo ships one collector config (`docker/telemetry/otel-collector-config.yaml`, three pipelines: traces, metrics, logs) plus a Grafana Cloud overlay that adds 0.5% tail sampling. A six-service Docker Compose stack — collector, Tempo, Loki, Prometheus, Grafana, renderer — gives a complete local environment.
-
-➡️ **[View full Configuration Reference](./05-configuration-reference.md)**
-
----
-
-## 6. Implementation Phases
-
-The plan was originally scoped at **13 weeks across 8 phases** — the table below
-is that original scope. As delivered it grew to **11 phases through week 20**;
-Phases 9-11 were added after the original plan was written. See
-[06-implementation-phases.md §6.12.6](./06-implementation-phases.md) for the
-authoritative per-phase status, and treat the eight rows below as the
-originally-planned subset rather than the current timeline:
-
-| Phase | Duration    | Focus                 | Key Deliverables                                          |
-| ----- | ----------- | --------------------- | --------------------------------------------------------- |
-| 1     | Weeks 1-2   | Core Infrastructure   | SDK integration, Telemetry interface, Configuration       |
-| 2     | Weeks 3-4   | RPC Tracing           | HTTP context extraction, Handler instrumentation          |
-| 3     | Weeks 5-6   | Transaction Tracing   | Protocol Buffer context, Relay propagation                |
-| 4     | Weeks 7-8   | Consensus Tracing     | Round spans, Proposal/validation tracing                  |
-| 5     | Week 9      | Documentation         | Runbook, Dashboards, Training                             |
-| 6     | Week 10     | StatsD Metrics Bridge | OTel Collector StatsD receiver, 3 Grafana dashboards      |
-| 7     | Weeks 11-12 | Native OTel Metrics   | OTelCollector impl, OTLP metrics export (StatsD retained) |
-| 8     | Week 13     | Log-Trace Correlation | trace_id in logs, Loki ingestion, Tempo↔Loki linking      |
-
-Delivered beyond the original scope: **Phase 9** (weeks 14-15, internal metric
-instrumentation gap fill), **Phase 10** (weeks 16-17, synthetic workload
-generation and telemetry validation) and **Phase 11** (weeks 18-20, third-party
-data-collection pipelines).
-
-**Total Effort**: 65.1 developer-days with 2 developers, for the eight
-originally-planned phases only.
-
-➡️ **[View full Implementation Phases](./06-implementation-phases.md)**
-
----
-
-## 7. Observability Backends
-
-> **APM** = Application Performance Monitoring | **GCS** = Google Cloud Storage
-
-Grafana Tempo is recommended for all environments due to its cost-effectiveness and Grafana integration, and it is the only backend this repo provisions. Elastic APM remains a reasonable choice for organizations with existing Elastic infrastructure, but nothing here configures it.
-
-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). Note that several subsections of doc 7 predate the shipped dashboards and alert rules and are marked superseded in place, pointing at [09-data-collection-reference.md](./09-data-collection-reference.md) and `docs/telemetry-runbook.md`.
-
-➡️ **[View Observability Backend Recommendations](./07-observability-backends.md)**
-
----
-
-## 8. Appendix
-
-The appendix contains a glossary of OpenTelemetry and xrpld-specific terms, references to external documentation and specifications, version history for this implementation plan, and a complete document index.
-
-➡️ **[View Appendix](./08-appendix.md)**
-
----
-
-## 9. Data Collection Reference
-
-A single-source-of-truth reference documenting every piece of telemetry data collected by xrpld: the OpenTelemetry span inventory with per-span attributes, the `beast::insight` and native `XRPL_METRIC_*` instruments (gauges, counters, histograms, overlay traffic), the SpanMetrics-derived Prometheus metrics, and the **15** Grafana dashboards. Includes Tempo search guides and Prometheus query examples. Consult that document rather than this index for any count — it tracks the code, this summary does not.
-
-➡️ **[View Data Collection Reference](./09-data-collection-reference.md)**
-
----
-
-## Securing the OTel Pipeline
-
-Threat model and hardening guidance for production deployments where xrpld nodes ship telemetry to a centrally-hosted collector across an untrusted network. Covers the two attack surfaces (collector ingress and peer trace-context spoofing) and the chosen defenses: mTLS as primary collector auth, NetworkPolicy as defense-in-depth, and source-side validation plus per-peer rate limiting for the `protocol::TraceContext` field on peer messages.
-
-➡️ **[View Securing the OTel Pipeline](./secure-OTel.md)**
-
----
-
-_This document provides a comprehensive implementation plan for integrating OpenTelemetry distributed tracing into the xrpld XRP Ledger node software. For detailed information on any section, follow the links to the corresponding sub-documents._

OpenTelemetryPlan/Phase10_taskList.md

@@ -1,308 +0,0 @@
-# Phase 10: Synthetic Workload Generation & Telemetry Validation — Task List
-
-> **Status**: Future Enhancement
->
-> **Goal**: Build tools that generate realistic XRPL traffic to validate the full Phases 1-9 telemetry stack end-to-end — all spans, attributes, metrics, dashboards, and log-trace correlation — under controlled load.
->
-> **Scope**: Python/shell test harness + multi-node docker-compose environment + automated validation scripts + performance benchmarks.
->
-> **Branch**: `pratik/otel-phase10-workload-validation` (from `pratik/otel-phase9-metric-gap-fill`)
->
-> **Depends on**: Phase 9 (internal metric gap fill) — validates the full metric surface
-
-### Related Plan Documents
-
-| Document                                                             | Relevance                                                       |
-| -------------------------------------------------------------------- | --------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)         | Phase 10 plan: motivation, architecture, exit criteria (§6.8.3) |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Defines the full inventory of spans/metrics to validate         |
-| [Phase9_taskList.md](./Phase9_taskList.md)                           | Prerequisite — all internal metrics must be emitting            |
-
-### Why This Phase Exists
-
-Before Phases 1-9 can be considered production-ready, we need proof that:
-
-1. Every emitted span fires with its required attributes under real transaction
-   workloads — the harness derives the span and attribute totals from
-   `expected_spans.json`, so no fixed "16 spans / 22 attributes" figure applies
-2. All 255+ StatsD metrics + ~50 Phase 9 metrics appear in Prometheus with non-zero values
-3. Log-trace correlation (Phase 8) produces clickable trace_id links in Loki
-4. The 14 harness-asserted Grafana dashboards render meaningful data (no empty
-   panels); 15 are on disk
-5. Performance overhead stays within bounds (< 3% CPU, < 5MB memory)
-6. The telemetry stack survives sustained load without data loss or queue backpressure
-
----
-
-## Task 10.1: Multi-Node Test Harness
-
-**Objective**: Create a docker-compose environment with 3-5 validator nodes that produces real consensus rounds.
-
-**What to do**:
-
-- Create `docker/telemetry/docker-compose.workload.yaml` — **as shipped this file
-  holds only the observability backend**: `otel-collector`, `tempo`,
-  `prometheus`, `loki`, `grafana`. It contains **no xrpld services**.
-  - Shared network (`workload-net`) with service discovery
-
-- The 5 validators are **native `xrpld` processes**, not containers.
-  `docker/telemetry/workload/run-full-validation.sh` (`NUM_NODES=5`) generates
-  keys, writes a per-node `xrpld.cfg`, and launches each node on
-  `127.0.0.1` with sequential RPC / WS / peer ports. Each node:
-  - Gets its validator key from `generate-validator-keys.sh`
-  - Lists the other 4 nodes in `ips_fixed`
-  - Has all telemetry enabled: `[telemetry] enabled=1`, `[insight] server=otel`
-  - Enables all trace categories including `trace_peer=1`
-  - Writes logs to a file tailed by the OTel Collector filelog receiver
-
-- ❌ **`make telemetry-workload-up` / `make telemetry-workload-down` were never
-  implemented.** There is no `Makefile` anywhere in the repository. The entry
-  point is `run-full-validation.sh` (with `--profile`, `--nodes`,
-  `--skip-loki`, `--skip-regression`, `--with-benchmark`). The node-count flag is
-  spelled `--nodes`, **not** `--num-nodes` — `run-full-validation.sh:80` (usage)
-  and `:100` (the `case` arm). `NUM_NODES` is the internal shell variable it
-  assigns to.
-
-**Key files**:
-
-- New: `docker/telemetry/docker-compose.workload.yaml` (backend only)
-- New: `docker/telemetry/workload/generate-validator-keys.sh`
-- New: `docker/telemetry/workload/run-full-validation.sh` — writes each node's
-  cfg **inline** via a heredoc at `run-full-validation.sh:242`
-  (`cat >"$NODE_DIR/xrpld.cfg" <<EOCFG`)
-- New: `docker/telemetry/workload/xrpld-validator.cfg.template` (96 lines) — it
-  **was** created and is tracked on the Phase 10 branch, but it is **unused**:
-  nothing reads it, and its `{{NODE_INDEX}}` / `{{RPC_PORT}}` / `{{OTEL_ENDPOINT}}`
-  placeholders are never substituted, because the inline heredoc above supersedes
-  it. Either wire the script to the template or delete the template — keeping both
-  guarantees they drift.
-
----
-
-## Task 10.2: RPC Load Generator
-
-**Objective**: Configurable tool that fires all traced RPC commands at controlled rates.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/rpc_load_generator.py`:
-  - Connects to one or more xrpld WebSocket endpoints
-  - Fires all RPC commands that have trace spans: `server_info`, `ledger`, `tx`, `account_info`, `account_lines`, `fee`, `submit`, etc.
-  - Configurable parameters: rate (RPS), duration, command distribution weights
-  - Injects `traceparent` HTTP headers to test W3C context propagation
-  - Logs progress and errors to stdout
-
-- Command distribution should match realistic production ratios:
-  - 40% `server_info` / `fee` (health checks)
-  - 30% `account_info` / `account_lines` / `account_objects` (wallet queries)
-  - 15% `ledger` / `ledger_data` (explorer queries)
-  - 10% `tx` / `account_tx` (transaction lookups)
-  - 5% `book_offers` / `amm_info` (DEX queries)
-
-**Key files**:
-
-- New: `docker/telemetry/workload/rpc_load_generator.py`
-- New: `docker/telemetry/workload/requirements.txt`
-
----
-
-## Task 10.3: Transaction Submitter
-
-**Objective**: Generate diverse transaction types to exercise `tx.*` and `ledger.*` spans.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/tx_submitter.py`:
-  - Pre-funds test accounts from genesis account
-  - Submits a mix of transaction types:
-    - `Payment` (XRP and issued currencies) — exercises `tx.process`, `tx.apply`
-    - `OfferCreate` / `OfferCancel` — DEX activity
-    - `TrustSet` — trust line creation for issued currencies
-    - `NFTokenMint` / `NFTokenCreateOffer` / `NFTokenAcceptOffer` — NFT activity
-    - `EscrowCreate` / `EscrowFinish` — escrow lifecycle
-    - `AMMCreate` / `AMMDeposit` / `AMMWithdraw` — AMM pool operations (if amendment enabled)
-  - Configurable: TPS target, transaction mix weights, duration
-  - Monitors submission results and tracks success/failure rates
-
-- The transaction mix ensures the telemetry captures the full range of ledger activity that third parties care about.
-
-**Key files**:
-
-- New: `docker/telemetry/workload/tx_submitter.py`
-- New: `docker/telemetry/workload/test_accounts.json` (pre-generated keypairs)
-
----
-
-## Task 10.4: Telemetry Validation Suite
-
-**Objective**: Automated scripts that verify all expected telemetry data exists after a workload run.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/validate_telemetry.py`:
-
-  **Span validation** (queries Tempo API):
-  - Assert every required span name in `expected_spans.json` appears in traces.
-    Conditional spans — `grpc.*`, `ledger.acquire`, `txq.*`,
-    `consensus.mode_change`, `rpc.process` — are marked `optional` and skipped
-    when the workload does not exercise them.
-  - Assert each span has its required attributes (bare/underscore keys; dotted
-    `xrpl.*` is reserved for resource attributes)
-  - Assert parent-child relationships are correct. The two live RPC trees are:
-    - HTTP: `rpc.http_request` -> `rpc.process` -> `rpc.command.*`
-    - WebSocket: `rpc.ws_message` -> `rpc.command.*` — **there is no
-      `rpc.process` on the WS path**. `rpc.process` is created only in
-      `ServerHandler::processRequest()` (`ServerHandler.cpp:705`), reached from
-      `processSession(Session, coro)`, i.e. HTTP only. Under WS-only load
-      `rpc.process` never appears, and `rpc.command.*` parents directly to
-      `rpc.ws_message`.
-  - Assert span durations are reasonable (> 0, < 60s)
-
-  **Metric validation** (queries Prometheus API):
-  - Assert all SpanMetrics-derived metrics are non-zero: `span_calls_total`,
-    `span_duration_milliseconds_bucket` (the connector's `namespace` is `span`,
-    not `traces_span_metrics` — `otel-collector-config.yaml:113-114`)
-  - Assert the insight-sourced metrics are non-zero: `ledgermaster_validated_ledger_age`,
-    `peer_finder_active_{inbound,outbound}_peers`, etc. — all lowercase, no
-    `xrpld_` prefix (`77f35c03db` removed the prefix and lowercased names)
-  - Assert all Phase 9 metrics are non-zero: `nodestore_state`, `cache_metrics`,
-    `txq_metrics`, `rpc_method_{started,finished,errored}_total`, `object_count`,
-    `load_factor_metrics`
-  - Assert metric label cardinality is within bounds
-
-  **Log-trace correlation validation** (queries Loki API):
-  - Assert logs contain `trace_id=` and `span_id=` fields
-  - Pick a random trace_id from Tempo → query Loki for matching logs → assert results exist
-  - Assert Grafana derived field links are functional
-
-  **Dashboard validation**:
-  - For each dashboard, query the dashboard API and assert no panels show "No
-    data". There are **15 dashboards on disk**; the harness asserts **14** —
-    `log-derived-insights` is provisioned but unasserted.
-
-- Output: JSON report with pass/fail per check, suitable for CI.
-
-**Key files**:
-
-- New: `docker/telemetry/workload/validate_telemetry.py`
-- New: `docker/telemetry/workload/expected_spans.json` (span inventory for validation)
-- New: `docker/telemetry/workload/expected_metrics.json` (metric inventory for validation)
-
----
-
-## Task 10.5: Performance Benchmark Suite
-
-**Objective**: Measure CPU/memory/latency overhead of the telemetry stack.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/benchmark.sh`:
-  - **Baseline run**: Start cluster with `[telemetry] enabled=0`, run transaction workload for 5 minutes, record metrics
-  - **Telemetry run**: Start cluster with full telemetry enabled, run identical workload, record metrics
-  - **Comparison**: Calculate deltas for:
-    - CPU usage (per-node average)
-    - Memory RSS (per-node peak)
-    - RPC p99 latency
-    - Transaction throughput (TPS)
-    - Consensus round time p95
-    - Ledger close time p95
-
-- Output: Markdown table comparing baseline vs. telemetry, with pass/fail against targets:
-  - CPU overhead < 3%
-  - Memory overhead < 5MB
-  - RPC latency impact < 2ms p99
-  - Throughput impact < 5%
-  - Consensus impact < 1%
-
-- Store results in `docker/telemetry/workload/benchmark-results/` for historical tracking.
-
-**Key files**:
-
-- New: `docker/telemetry/workload/benchmark.sh`
-- New: `docker/telemetry/workload/collect_system_metrics.sh`
-
----
-
-## Task 10.6: CI Integration
-
-**Objective**: Wire the validation suite into CI for regression detection.
-
-**What to do**:
-
-- Create a CI workflow (GitHub Actions or equivalent) that:
-  1. Builds xrpld with `-DXRPL_ENABLE_TELEMETRY=ON`
-  2. Starts the multi-node workload harness
-  3. Runs the RPC load generator + transaction submitter for 2 minutes
-  4. Runs the validation suite
-  5. Runs the benchmark suite
-  6. Fails the build if any validation check fails or benchmark exceeds thresholds
-  7. Archives the validation report and benchmark results as artifacts
-
-- This should be a separate workflow (not part of the main CI), triggered manually or on telemetry-related branch changes.
-
-**Key files**:
-
-- New: `.github/workflows/telemetry-validation.yml`
-- New: `docker/telemetry/workload/run-full-validation.sh` (orchestrator script)
-
----
-
-## Task 10.7: Documentation
-
-**Objective**: Document the workload tools and validation process.
-
-**What to do**:
-
-- Create `docker/telemetry/workload/README.md`:
-  - Quick start guide for running workload harness
-  - Configuration options for load generator and tx submitter
-  - How to read validation reports
-  - How to run benchmarks and interpret results
-
-- Update `docs/telemetry-runbook.md`:
-  - Add "Validating Telemetry Stack" section
-  - Add "Performance Benchmarking" section
-
-- Update `OpenTelemetryPlan/09-data-collection-reference.md`:
-  - Add "Validation" section with expected metric/span counts
-
----
-
-## Exit Criteria — Delivered in PR #6519
-
-- [x] 5-node validator cluster starts and reaches consensus — as native `xrpld`
-      processes driven by `run-full-validation.sh` (`NUM_NODES=5`), not from
-      docker-compose
-- [x] RPC load generator fires all traced RPC commands at configurable rates
-- [x] Transaction submitter generates 6+ transaction types at configurable TPS
-- [x] Validation suite confirms the full span / attribute / metric inventory
-      (totals computed dynamically from `expected_spans.json` /
-      `expected_metrics.json`)
-- [x] Log-trace correlation validated end-to-end (Loki <-> Tempo) — implemented
-      and passing locally, but CI runs with `--skip-loki`, so it is not gated
-- [x] All 14 harness-asserted Grafana dashboards render data (no empty panels);
-      15 on disk, `log-derived-insights` unasserted
-- [x] Overhead benchmark (`benchmark.sh`) measures telemetry-off vs telemetry-on
-      deltas
-- [ ] Benchmark shows < 3% CPU overhead, < 5MB memory overhead — needs a
-      measured run
-- [x] CI workflow runs validation on telemetry branch changes
-- [x] Validation report output is CI-parseable (JSON with exit codes)
-- [x] OTel-driven regression gate captures per-span and per-job timings from
-      Prometheus and compares against a committed baseline. Per-RPC timings are
-      **not** gated: `regression-metrics.json` defines only `spans` and
-      `job_queue` groups (FU-4).
-
-## Follow-up Work (tracked in separate PRs)
-
-- [ ] FU-2: Automate baseline persistence across CI runs (artifact uploaded
-      on merge to `develop`, downloaded on PR runs). Current mechanism
-      requires a manual baseline-refresh PR.
-- [ ] FU-4: Replace the proxy measurements in `benchmark.sh` (wall-clock curl
-      p99, ledger-cadence-as-TPS, ledger-cadence-as-consensus-p95) with
-      PromQL quantile queries from the same pipeline the regression gate uses,
-      and add an `rpc_methods` group to `regression-metrics.json` plus a
-      `defaults.rpc_method` block to `regression-thresholds.json` (without both,
-      any `rpc.*` metric resolves to "no threshold configured" and never gates).
-- [ ] FU-6: Grafana dashboard plotting historical baseline values keyed by
-      commit SHA, for triaging noisy regressions.

OpenTelemetryPlan/Phase11_taskList.md

@@ -1,664 +0,0 @@
-# Phase 11: Third-Party Data Collection Pipelines — Task List
-
-> **Status**: Not started — 0 of 13 tasks complete (`grep -c '^## Task 11\.'` = 13:
-> Tasks 11.1 through 11.13). Verified against the tree:
-> no `.go` files exist anywhere, `docker/telemetry/otel-rippled-receiver/` does
-> not exist, `docker/telemetry/prometheus/` does not exist (so no
-> `prometheus/rippled-alerts.yml`), and no `network-topology` / `dex-amm`
-> dashboards are present under `docker/telemetry/grafana/dashboards/`. **No Phase 11 work has
-> been done, so no task box below may be ticked.**
->
-> One **prerequisite** box is ticked, and only one: Task 11.12's
-> "`state_tracking` gauge implemented (Task 7.12)". That is an upstream
-> dependency satisfied by Phase 7/9 code, not Phase 11 work — see the citation
-> there.
->
-> **Goal**: Build a custom OTel Collector receiver that periodically polls xrpld's admin RPCs and exports structured metrics for external consumers — making all XRPL health, validator, peer, fee, and DEX data available as Prometheus/OTLP metrics without xrpld code changes.
->
-> **Scope**: Go-based OTel Collector receiver plugin + Grafana dashboards + Prometheus alerting rules.
->
-> **Branch**: `pratik/otel-phase11-third-party-collection` (from `pratik/otel-phase10-workload-validation`)
->
-> **Depends on**: Phase 10 (validation harness for testing the new receiver)
-
-### Related Plan Documents
-
-| Document                                                             | Relevance                                                       |
-| -------------------------------------------------------------------- | --------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)         | Phase 11 plan: motivation, architecture, exit criteria (§6.8.4) |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Defines full metric inventory including third-party metrics     |
-| [Phase10_taskList.md](./Phase10_taskList.md)                         | Prerequisite — validation harness for testing                   |
-
-### Third-Party Consumer Gap Analysis
-
-This phase addresses the cross-cutting gap identified during research: **xrpld has no native Prometheus/OTLP metrics export for data accessible only via RPC**. Every consumer (exchanges, payment processors, analytics providers, validators, researchers, compliance firms, custodians) must build custom JSON-RPC polling and conversion. This receiver centralizes that work.
-
-| Consumer Category          | Data Unlocked by This Phase                                        |
-| -------------------------- | ------------------------------------------------------------------ |
-| **Exchanges**              | Real-time fee estimates, TxQ capacity, server health scores        |
-| **Payment Processors**     | Settlement latency percentiles, corridor health, path availability |
-| **Analytics Providers**    | Validator metrics, network topology, amendment voting status       |
-| **DeFi / AMM**             | AMM pool TVL, DEX order book depth, trade volumes                  |
-| **Validators / Operators** | Per-peer latency, version distribution, UNL health, alerting       |
-| **Compliance**             | Transaction volume trends, network growth metrics                  |
-| **Academic Researchers**   | Consensus performance time-series, decentralization metrics        |
-| **CBDC / Tokenization**    | Token supply tracking, trust line adoption, freeze status          |
-| **Institutional Custody**  | Multi-sig status, escrow tracking, reserve calculations            |
-| **Wallet Providers**       | Server health for node selection, fee prediction data              |
-
----
-
-## Task 11.1: OTel Collector Receiver Scaffold
-
-**Objective**: Create the Go project structure for a custom OTel Collector receiver that polls xrpld JSON-RPC.
-
-**What to do**:
-
-- Create `docker/telemetry/otel-rippled-receiver/`:
-  - `receiver.go` — implements `receiver.Metrics` interface
-  - `config.go` — configuration struct (endpoint, poll interval, enabled RPCs)
-  - `factory.go` — receiver factory registration
-  - `go.mod` / `go.sum` — Go module with OTel Collector SDK dependency
-
-- Configuration model:
-
-  ```yaml
-  xrpld_receiver:
-    endpoint: "http://localhost:5005" # xrpld admin RPC
-    poll_interval: 30s # how often to poll
-    enabled_collectors:
-      - server_info
-      - get_counts
-      - fee
-      - peers
-      - validators
-      - feature
-      - server_state
-    amm_pools: [] # optional: AMM pool IDs to track
-    book_offers_pairs: [] # optional: currency pairs for DEX depth
-  ```
-
-- Build a custom OTel Collector binary that includes this receiver alongside the standard receivers.
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/receiver.go`
-- New: `docker/telemetry/otel-rippled-receiver/config.go`
-- New: `docker/telemetry/otel-rippled-receiver/factory.go`
-- New: `docker/telemetry/otel-rippled-receiver/go.mod`
-- New: `docker/telemetry/otel-rippled-receiver/Dockerfile`
-
----
-
-## Task 11.2: server_info / server_state Collector
-
-**Objective**: Poll `server_info` and `server_state` and export all fields as OTel metrics.
-
-**What to do**:
-
-- Implement `serverInfoCollector` that calls `server_info` (admin) and extracts:
-
-  **Node Health Gauges:**
-  - `xrpl_server_state` (enum → int: disconnected=0, connected=1, syncing=2, tracking=3, full=4, proposing=5)
-  - `xrpl_server_state_duration_seconds`
-  - `xrpl_uptime_seconds`
-  - `xrpl_io_latency_ms`
-  - `xrpl_amendment_blocked` (0 or 1)
-  - `xrpl_peers_count`
-  - `xrpl_peer_disconnects_total`
-  - `xrpl_peer_disconnects_resources_total`
-  - `xrpl_jq_trans_overflow_total`
-
-  **Consensus Gauges:**
-  - `xrpl_last_close_proposers`
-  - `xrpl_last_close_converge_time_seconds`
-  - `xrpl_validation_quorum`
-
-  **Ledger Gauges:**
-  - `xrpl_validated_ledger_seq`
-  - `xrpl_validated_ledger_age_seconds`
-  - `xrpl_validated_ledger_base_fee_drops`
-  - `xrpl_validated_ledger_reserve_base_drops`
-  - `xrpl_validated_ledger_reserve_inc_drops`
-  - `xrpl_close_time_offset_seconds` (0 when absent)
-
-  **Load Factor Gauges:**
-  - `xrpl_load_factor`
-  - `xrpl_load_factor_server`
-  - `xrpl_load_factor_fee_escalation`
-  - `xrpl_load_factor_fee_queue`
-  - `xrpl_load_factor_local`
-  - `xrpl_load_factor_net`
-  - `xrpl_load_factor_cluster`
-
-  **State Accounting Gauges** (per state: disconnected, connected, syncing, tracking, full):
-  - `xrpl_state_duration_seconds{state="<name>"}`
-  - `xrpl_state_transitions_total{state="<name>"}`
-
-  **Validator Info** (when node is a validator):
-  - `xrpl_validator_list_count`
-  - `xrpl_validator_list_expiration_seconds` (epoch)
-  - `xrpl_validator_list_active` (0 or 1)
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/server_info.go`
-
----
-
-## Task 11.3: get_counts Collector
-
-**Objective**: Poll `get_counts` and export internal object counts and NodeStore stats.
-
-**What to do**:
-
-- Implement `getCountsCollector`:
-
-  **Database Gauges:**
-  - `xrpl_db_size_kb{db="total"}`, `xrpl_db_size_kb{db="ledger"}`, `xrpl_db_size_kb{db="transaction"}`
-
-  **NodeStore Gauges:**
-  - `xrpl_nodestore_reads_total`, `xrpl_nodestore_reads_hit`, `xrpl_nodestore_writes_total`
-  - `xrpl_nodestore_read_bytes`, `xrpl_nodestore_written_bytes`
-  - `xrpl_nodestore_read_duration_us`, `xrpl_nodestore_write_load`
-  - `xrpl_nodestore_read_queue`, `xrpl_nodestore_read_threads_running`
-
-  **Cache Gauges:**
-  - `xrpl_cache_hit_rate{cache="SLE"}`, `xrpl_cache_hit_rate{cache="ledger"}`, `xrpl_cache_hit_rate{cache="accepted_ledger"}`
-  - `xrpl_cache_size{cache="treenode"}`, `xrpl_cache_size{cache="fullbelow"}`, `xrpl_cache_size{cache="accepted_ledger"}`
-
-  **Object Count Gauges:**
-  - `xrpl_object_count{type="<name>"}` for each counted object type (Transaction, Ledger, NodeObject, STTx, STLedgerEntry, InboundLedger, Pathfinder, etc.)
-
-  **Rates:**
-  - `xrpl_historical_fetch_per_minute`
-  - `xrpl_local_txs`
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/get_counts.go`
-
----
-
-## Task 11.4: Peer Topology Collector
-
-**Objective**: Poll `peers` and export per-peer and aggregate network metrics.
-
-**What to do**:
-
-- Implement `peersCollector`:
-
-  **Aggregate Gauges:**
-  - `xrpl_peers_inbound_count`
-  - `xrpl_peers_outbound_count`
-  - `xrpl_peers_cluster_count`
-
-  **Per-Peer Gauges** (with labels `peer_key` truncated to 8 chars for cardinality control):
-  - `xrpl_peer_latency_ms{peer="<key>", version="<ver>", inbound="<bool>"}`
-  - `xrpl_peer_uptime_seconds{peer="<key>"}`
-  - `xrpl_peer_load{peer="<key>"}`
-
-  **Distribution Gauges** (aggregated across all peers):
-  - `xrpl_peer_latency_p50_ms`, `xrpl_peer_latency_p95_ms`, `xrpl_peer_latency_p99_ms`
-  - `xrpl_peer_version_count{version="<semver>"}` — count of peers per software version
-
-  **Tracking Status:**
-  - `xrpl_peer_diverged_count` — peers with `track=diverged`
-  - `xrpl_peer_unknown_count` — peers with `track=unknown`
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/peers.go`
-
-**Cardinality note**: Per-peer metrics use truncated keys. For large peer sets (50+), the aggregate distribution gauges are preferred over per-peer labels.
-
----
-
-## Task 11.5: Validator & Amendment Collector
-
-**Objective**: Poll `validators` and `feature` to export validator health and amendment voting status.
-
-**What to do**:
-
-- Implement `validatorCollector`:
-
-  **From `validators` RPC:**
-  - `xrpl_trusted_validators_count`
-  - `xrpl_validator_signing` (0 or 1 — whether local validator is signing)
-
-  **From `feature` RPC:**
-  - `xrpl_amendment_enabled_count` — total enabled amendments
-  - `xrpl_amendment_majority_count` — amendments with majority but not yet enabled
-  - `xrpl_amendment_vetoed_count` — locally vetoed amendments
-  - `xrpl_amendment_unsupported_majority` (0 or 1) — any unsupported amendment has majority (critical alert)
-
-  **Per-amendment with majority** (limited cardinality — only amendments with `majority` set):
-  - `xrpl_amendment_majority_time{name="<amendment>"}` — epoch time when majority was gained
-  - `xrpl_amendment_votes{name="<amendment>"}` — current vote count
-  - `xrpl_amendment_threshold{name="<amendment>"}` — votes needed
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/validators.go`
-
----
-
-## Task 11.6: Fee & TxQ Collector
-
-**Objective**: Poll `fee` RPC and export real-time fee market data.
-
-**What to do**:
-
-- Implement `feeCollector` that calls the public `fee` RPC:
-
-  **Fee Level Gauges:**
-  - `xrpl_fee_current_ledger_size` — transactions in current open ledger
-  - `xrpl_fee_expected_ledger_size` — expected transactions at close
-  - `xrpl_fee_max_queue_size` — maximum transaction queue size
-  - `xrpl_fee_open_ledger_fee_drops` — minimum fee for open ledger inclusion
-  - `xrpl_fee_median_fee_drops` — median fee level
-  - `xrpl_fee_minimum_fee_drops` — base reference fee
-  - `xrpl_fee_queue_size` — current queue depth
-
-- This overlaps with Phase 9's internal TxQ metrics but provides an external-only collection path that doesn't require xrpld code changes.
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/fee.go`
-
----
-
-## Task 11.7: DEX & AMM Collector (Optional)
-
-**Objective**: Periodically poll configured AMM pools and order book pairs for DeFi metrics.
-
-**What to do**:
-
-- Implement `dexCollector` (enabled only when `amm_pools` or `book_offers_pairs` are configured):
-
-  **AMM Pool Gauges** (per configured pool):
-  - `xrpl_amm_reserve{pool="<id>", asset="<currency>"}` — pool reserve amount
-  - `xrpl_amm_lp_token_supply{pool="<id>"}` — outstanding LP tokens
-  - `xrpl_amm_trading_fee{pool="<id>"}` — pool trading fee (basis points)
-  - `xrpl_amm_tvl_drops{pool="<id>"}` — total value locked (XRP-denominated)
-
-  **Order Book Gauges** (per configured pair):
-  - `xrpl_orderbook_bid_depth{pair="<base>/<quote>"}` — total bid volume
-  - `xrpl_orderbook_ask_depth{pair="<base>/<quote>"}` — total ask volume
-  - `xrpl_orderbook_spread{pair="<base>/<quote>"}` — best bid-ask spread
-  - `xrpl_orderbook_offer_count{pair="<base>/<quote>", side="bid|ask"}` — number of offers
-
-**Key files**:
-
-- New: `docker/telemetry/otel-rippled-receiver/collectors/dex.go`
-
-**Note**: This is optional because it requires explicit configuration of which pools/pairs to track. Default configuration tracks no DEX data.
-
----
-
-## Task 11.8: Prometheus Alerting Rules
-
-**Objective**: Create production-ready alerting rules for the `xrpl_*` metrics
-exported by this receiver.
-
-> **Scope note — do not duplicate Phase 9.** Phase 9 already ships provisioned
-> **Grafana** alerting at
-> `docker/telemetry/grafana/provisioning/alerting/{rules,contactpoints,policies}.yaml`
-> — 13 rules in 5 groups, 2 contact points (`xrpld-default` Slack,
-> `xrpld-critical` Slack + email), and a nested notification policy keyed on
-> `severity = critical`. Four of the rules below overlap it:
->
-> | Rule here           | Addressed by (Phase 9)                            | Coverage                                                                                                         |
-> | ------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-> | `XRPLServerNotFull` | `NodeNotFull` (group `xrpld-node-state`)          | Full                                                                                                             |
-> | `XRPLLedgerStale`   | `ValidatedLedgerStale` (group `xrpld-consensus`)  | **Partial** — Phase 9: `ledgermaster_validated_ledger_age > 60` for 5m; the external shape is `> 30` for 1m      |
-> | `XRPLHighIOLatency` | `NodeStoreIOLatencyHigh` (group `xrpld-jobqueue`) | **Partial** — Phase 9: p95 of `ios_latency_milliseconds_bucket` **> 1000 ms for 10m**; external: **> 50 for 1m** |
-> | `XRPLStateFlapping` | `NodeStateFlapping` (group `xrpld-node-state`)    | Full                                                                                                             |
->
-> The remaining 8 (`XRPLAmendmentBlocked`, `XRPLNoPeers`,
-> `XRPLUnsupportedAmendmentMajority`, `XRPLLowPeerCount`, `XRPLHighLoadFactor`,
-> `XRPLSlowConsensus`, `XRPLValidatorListExpiring`, `XRPLClockDrift`) are
-> genuinely new. Note the two sets watch different metric surfaces — the Phase 9
-> rules fire on xrpld's own OTLP metrics, these on the receiver's `xrpl_*`
-> metrics — so if both are kept, dedupe the notification policy to avoid
-> double-paging on the same underlying condition.
->
-> `docker/telemetry/prometheus/` does not exist today. Prefer extending the
-> Phase 9 Grafana provisioning tree over introducing a second, Prometheus-native
-> alerting mechanism; if a `prometheus/` tree is added anyway, say explicitly in
-> its header which alerts it owns.
-
-**What to do**:
-
-- Create `docker/telemetry/prometheus/rippled-alerts.yml`:
-
-  **Tier 1 — Critical (page immediately):**
-
-  ```yaml
-  - alert: XRPLServerNotFull
-    expr: xrpl_server_state < 4
-    for: 15m
-
-  - alert: XRPLAmendmentBlocked
-    expr: xrpl_amendment_blocked == 1
-    for: 1m
-
-  - alert: XRPLNoPeers
-    expr: xrpl_peers_count == 0
-    for: 5m
-
-  - alert: XRPLLedgerStale
-    expr: xrpl_validated_ledger_age_seconds > 120
-    for: 2m
-
-  - alert: XRPLHighIOLatency
-    expr: xrpl_io_latency_ms > 100
-    for: 5m
-
-  - alert: XRPLUnsupportedAmendmentMajority
-    expr: xrpl_amendment_unsupported_majority == 1
-    for: 1m
-  ```
-
-  **Tier 2 — Warning (investigate within hours):**
-
-  ```yaml
-  - alert: XRPLLowPeerCount
-    expr: xrpl_peers_count < 10
-    for: 15m
-
-  - alert: XRPLHighLoadFactor
-    expr: xrpl_load_factor > 10
-    for: 10m
-
-  - alert: XRPLSlowConsensus
-    expr: xrpl_last_close_converge_time_seconds > 6
-    for: 5m
-
-  - alert: XRPLValidatorListExpiring
-    expr: (xrpl_validator_list_expiration_seconds - time()) < 86400
-    for: 1h
-
-  - alert: XRPLClockDrift
-    expr: xrpl_close_time_offset_seconds > 0
-    for: 5m
-
-  - alert: XRPLStateFlapping
-    expr: rate(xrpl_state_transitions_total{state="full"}[1h]) > 2
-    for: 30m
-  ```
-
-**Key files**:
-
-- New: `docker/telemetry/prometheus/rippled-alerts.yml`
-- Update: `docker/telemetry/prometheus/prometheus.yml` (add rule_files reference)
-
----
-
-## Task 11.9: New Grafana Dashboards
-
-**Objective**: Create 4 new dashboards for the data exported by the receiver.
-
-> **UID COLLISION — pick a different uid.** Phase 9 already ships
-> `docker/telemetry/grafana/dashboards/validator-health.json` with
-> **uid `validator-health`** (17 panels, backed by xrpld's own
-> `validation_agreement` / `validator_health` / `state_tracking` OTLP metrics).
-> Provisioning a second dashboard with the same uid makes Grafana overwrite one
-> with the other — whichever the provisioner loads last wins, silently. Use a
-> distinct uid such as `validator-health-external` (and a distinct filename), the
-> same way this task already disambiguates Fee Market as
-> `xrpld-fee-market-external` against Phase 9's `fee-market`. Also check
-> `peer-quality`, `fee-market`, `job-queue` and `node-health` before adding any
-> further uid.
-
-**What to do**:
-
-- **Validator Health** (`validator-health-external` — **not** `validator-health`,
-  see the collision note above):
-  - Server state timeline, state duration breakdown
-  - Proposer count trend, converge time trend, validation quorum
-  - Validator list expiration countdown
-  - Amendment voting status (majority/enabled/vetoed)
-
-- **Network Topology** (`xrpld-network-topology`):
-  - Peer count (inbound/outbound/cluster), peer version distribution
-  - Peer latency distribution (p50/p95/p99), diverged peer count
-  - Geographic distribution (if enriched with GeoIP)
-  - Peer uptime distribution
-
-- **Fee Market** (`xrpld-fee-market-external`):
-  - Current fee levels (open ledger, median, minimum), fee escalation timeline
-  - Queue depth vs. capacity, transactions per ledger
-  - Load factor breakdown (server/network/cluster/escalation)
-
-- **DEX & AMM Overview** (`xrpld-dex-amm`) (only populated when DEX collectors are configured):
-  - AMM pool TVL, reserve ratios, LP token supply
-  - Order book depth per pair, spread trends
-  - Trading fee revenue estimates
-
-**Key files**:
-
-- New: `docker/telemetry/grafana/dashboards/validator-health-external.json`
-  (**must not** reuse Phase 9's `validator-health.json` / uid `validator-health`)
-- New: `docker/telemetry/grafana/dashboards/network-topology.json`
-- New: `docker/telemetry/grafana/dashboards/fee-market-external.json`
-  (Phase 9 owns `fee-market.json` / uid `fee-market`)
-- New: `docker/telemetry/grafana/dashboards/dex-amm.json`
-
-> Filenames drop the legacy `dashboards/rippled-*` prefix: `145b1469d6` and
-> `25868f2740` renamed every dashboard to bare names with bare uids, so no
-> `dashboards/rippled-*.json` path exists in the tree.
-
----
-
-## Task 11.10: Integration with Phase 10 Validation
-
-**Objective**: Extend the Phase 10 validation suite to verify this receiver's metrics.
-
-**What to do**:
-
-- Update `docker/telemetry/workload/validate_telemetry.py`:
-  - Add assertions for all `xrpl_*` metrics produced by the receiver
-  - Verify metric labels have expected values
-  - Verify alerting rules fire correctly (inject a "bad" state and check alert)
-
-- Update `docker/telemetry/docker-compose.workload.yaml`:
-  - Add the custom OTel Collector build with the xrpld receiver
-  - Configure the receiver to poll one of the test nodes
-
-**Key files**:
-
-- Update: `docker/telemetry/workload/validate_telemetry.py`
-- Update: `docker/telemetry/docker-compose.workload.yaml`
-- Update: `docker/telemetry/workload/expected_metrics.json`
-
----
-
-## Task 11.11: Documentation
-
-**Objective**: Document the receiver, its metrics, deployment, and alerting.
-
-**What to do**:
-
-- Create `docker/telemetry/otel-rippled-receiver/README.md`:
-  - Architecture overview (how the receiver fits into the OTel Collector)
-  - Configuration reference (all config options with defaults)
-  - Metric reference table (all exported metrics with types and labels)
-  - Deployment guide (building custom collector binary, docker-compose integration)
-
-- Update `OpenTelemetryPlan/09-data-collection-reference.md`:
-  - Add "Third-Party Metrics (OTel Collector Receiver)" section
-  - Add new Grafana dashboard reference (4 dashboards)
-  - Add alerting rules reference
-
-- Update `docs/telemetry-runbook.md`:
-  - Add "Third-Party Metrics Receiver" troubleshooting section
-  - Add alerting playbook (what to do for each Tier 1/Tier 2 alert)
-
----
-
-## Task 11.12: Alert Rules for External Dashboard Parity Metrics
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity) — 18 alert rules ported from the community [xrpl-validator-dashboard](https://github.com/realgrapedrop/xrpl-validator-dashboard).
->
-> **Upstream**: Phase 7 Tasks 7.9-7.16 (metrics), Phase 9 Tasks 9.11-9.13 (dashboards).
-> **Downstream**: None — terminal task in the parity chain.
-
-**Objective**: Add Grafana alerting rules for the Phase 7+ parity metrics (validation agreement, validator health, peer quality, state tracking, ledger economy). These complement Task 11.8's `xrpl_*` alerts by covering the internal metrics.
-
-> **4 of the 18 are addressed by Phase 9** — 2 fully, 2 only partially. Extend,
-> do not blindly re-create:
->
-> | Rule here          | Addressed by (Phase 9)                                                                      | Coverage                                                                                                                                                                    |
-> | ------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-> | Unhealthy State    | `NodeNotFull` (group `xrpld-node-state`)                                                    | Full                                                                                                                                                                        |
-> | High IO Latency    | `NodeStoreIOLatencyHigh` (group `xrpld-jobqueue`, p95 of `ios_latency_milliseconds_bucket`) | **Partial** — Phase 9 fires at p95 **> 1000 ms for 10m**; the rule below wants **> 50 for 1m** (20× tighter)                                                                |
-> | Job Queue Overflow | `JobQueueTxOverflow` (group `xrpld-jobqueue`, `jq_trans_overflow_total`)                    | Full                                                                                                                                                                        |
-> | Stale Ledger       | `ValidatedLedgerStale` (group `xrpld-consensus`, `ledgermaster_validated_ledger_age`)       | **Partial** — different metric: Phase 9 uses `ledgermaster_validated_ledger_age > 60` for 5m; the rule below uses `ledger_economy{metric="ledger_age_seconds"} > 30` for 1m |
->
-> The two **Partial** rows are not closed. Either re-baseline the Phase 9
-> thresholds or ship the tighter variants here — do not skip them as duplicates.
->
-> Remaining open work is **14 rules**, of which **3** (CPU High, Memory Critical,
-> Disk Warning) need `node_exporter`, which is not in the stack. Nothing else is
-> blocked: "Not Proposing" used to be listed as blocked on an unimplemented
-> `state_tracking` gauge, but that gauge **ships** — see the Exit Criteria note
-> below.
->
-> **Metric-name translation.** Names carry **no** `xrpld_` prefix
-> (`77f35c03db`), so as a rule of thumb read every `xrpld_<name>` below as plain
-> `<name>`. **Two shapes do not follow that rule:**
->
-> - **Multiplexed observable gauges.** Many readings are a `metric` **label
->   value** on a shared instrument, not a metric name. `xrpld_txq_count` is
->   `txq_metrics{metric="txq_count"}`; likewise `load_factor_metrics{…}`,
->   `nodestore_state{…}`, `cache_metrics{…}`. The rows below that already use the
->   `<instrument>{metric="…"}` form (`state_tracking`, `validator_health`,
->   `validation_agreement`, `server_info`, `peer_quality`, `load_factor_metrics`,
->   `ledger_economy`) are correct; only drop the prefix on those.
-> - **Unit-suffixed histograms** from `beast::insight`. `OTelCollectorImp` appends
->   the unit, so `xrpld_ios_latency_bucket` is really
->   `ios_latency_milliseconds_bucket` — the spelling used by
->   `node-health.json:577` and `ledger-data-sync.json:1353`.
-
-**Critical Group** (8 rules, eval interval 10s):
-
-| Rule                | Condition                                                        | For |
-| ------------------- | ---------------------------------------------------------------- | --- |
-| Agreement Below 90% | `xrpld_validation_agreement{metric="agreement_pct_24h"} < 90`    | 30s |
-| Not Proposing       | `xrpld_state_tracking{metric="state_value"} < 6`                 | 10s |
-| Unhealthy State     | `xrpld_state_tracking{metric="state_value"} < 4`                 | 10s |
-| Amendment Blocked   | `xrpld_validator_health{metric="amendment_blocked"} == 1`        | 1m  |
-| UNL Expiring        | `xrpld_validator_health{metric="unl_expiry_days"} < 14`          | 1h  |
-| High IO Latency     | `histogram_quantile(0.95, ios_latency_milliseconds_bucket) > 50` | 1m  |
-| High Load Factor    | `xrpld_load_factor_metrics{metric="load_factor"} > 1000`         | 1m  |
-| Peer Count Critical | `xrpld_server_info{metric="peers"} < 5`                          | 1m  |
-
-**Network Group** (3 rules, eval interval 10s):
-
-| Rule                      | Condition                                                         | For |
-| ------------------------- | ----------------------------------------------------------------- | --- |
-| Peer Drop >10%            | `delta(xrpld_server_info{metric="peers"}[30s]) / ... * 100 < -10` | 30s |
-| Peer Drop >30%            | Same formula, threshold -30                                       | 30s |
-| P90 Latency + Disconnects | `peer_latency_p90_ms > 500 AND rate(disconnects) > 0`             | 2m  |
-
-**Performance Group** (7 rules, eval interval 10s):
-
-| Rule                | Condition                                                    | For |
-| ------------------- | ------------------------------------------------------------ | --- |
-| CPU High            | Per-core CPU > 80% (requires node_exporter)                  | 2m  |
-| Memory Critical     | Memory usage > 90% (requires node_exporter)                  | 1m  |
-| Disk Warning        | Disk usage > 85% (requires node_exporter)                    | 2m  |
-| Job Queue Overflow  | `rate(xrpld_jq_trans_overflow_total[5m]) > 0`                | 1m  |
-| Upgrade Recommended | `xrpld_peer_quality{metric="peers_higher_version_pct"} > 60` | 1m  |
-| TX Rate Drop        | Transaction rate dropped > 50% in 5m window                  | 5m  |
-| Stale Ledger        | `xrpld_ledger_economy{metric="ledger_age_seconds"} > 30`     | 1m  |
-
-**Notification channel templates**: Slack and Email/SMTP already ship in Phase
-9's `contactpoints.yaml` (`xrpld-default`, `xrpld-critical`). Discord and
-PagerDuty templates remain open.
-
-**Key files** — extend the **Phase 9** provisioning tree. The
-`docker/telemetry/grafana/alerting/` directory named in the original spec has
-never existed in any commit; the real location is
-`docker/telemetry/grafana/provisioning/alerting/`:
-
-- Extend: `docker/telemetry/grafana/provisioning/alerting/rules.yaml` (add groups
-  alongside the existing `xrpld-consensus`, `xrpld-validator`, `xrpld-jobqueue`,
-  `xrpld-node-state`, `xrpld-overlay`)
-- Extend: `docker/telemetry/grafana/provisioning/alerting/contactpoints.yaml`
-  (add Discord / PagerDuty receivers)
-- Extend: `docker/telemetry/grafana/provisioning/alerting/policies.yaml`
-  (add routes; the root route and the `severity = critical` child already exist)
-
-**Exit Criteria**:
-
-- [ ] The 14 not-yet-shipped rules evaluate without errors in Grafana alerting UI
-- [ ] The 2 rules **fully** covered by Phase 9 (Unhealthy State, Job Queue
-      Overflow) are not duplicated; the 2 **partially** covered ones (High IO
-      Latency, Stale Ledger) are either re-baselined on the Phase 9 rule or shipped
-      as tighter variants — decision recorded either way
-- [ ] Critical rules fire within expected timeframe when conditions are met
-- [ ] Notification channel templates are documented (not hard-coded to any service)
-- [ ] `node_exporter` decision recorded for the 3 host-level rules (CPU, memory, disk)
-- [x] `state_tracking` gauge implemented (Task 7.12) before adding "Not Proposing"
-      — **prerequisite met upstream**, not Phase 11 work.
-      `MetricsRegistry::registerStateTrackingGauge()`
-      (`src/xrpld/telemetry/MetricsRegistry.cpp:1461-1510`) creates
-      `CreateDoubleObservableGauge("state_tracking", "Node state and mode tracking")`
-      at `:1466` and observes `state_value` (`:1497`) and
-      `time_in_current_state_seconds` (`:1502`). Already queried by
-      `validator-health.json:765,971` and `ledger-data-sync.json:869`, and
-      documented in
-      [09-data-collection-reference.md](./09-data-collection-reference.md)
-      § State Tracking. "Not Proposing" can be written now.
-
----
-
-## Task 11.13: Dual-Datasource Architecture Documentation
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Document the external dashboard's "fast path" pattern as a future optimization for real-time panels.
-
-**Pattern**: A lightweight Prometheus scrape endpoint (separate from OTLP pipeline) that polls critical metrics every 2-5s, bypassing the 10s OTLP metric reader interval and Prometheus scrape interval.
-
-**Use case**: Real-time state panels (server state, ledger age, peer count) where 10-15s latency is too slow for operational dashboards.
-
-**Decision**: Document as a future option, not implement now. The current 10s interval is acceptable for v1. The external dashboard achieves 2-5s freshness by polling RPC directly, which is what the Phase 11 receiver already does. Adding a separate scrape endpoint to xrpld would only be needed if sub-second metric freshness is required from the internal metrics pipeline.
-
-**What to document**:
-
-- Architecture comparison: OTLP pipeline (10-15s) vs. direct scrape (2-5s) vs. push gateway
-- When to consider: operator feedback indicating 10s is insufficient for alerting SLOs
-- How to implement if needed: add `/metrics` HTTP endpoint to xrpld with Prometheus client library
-- Trade-offs: additional port, additional dependency, duplication with OTLP metrics
-
-**Key files**:
-
-- Update: `OpenTelemetryPlan/09-data-collection-reference.md` (add "Future: Dual-Datasource Architecture" section)
-- Update: `docs/telemetry-runbook.md` (add brief note in performance tuning section)
-
-**Exit Criteria**:
-
-- [ ] Architecture comparison documented with clear trade-offs
-- [ ] Decision rationale recorded (why deferred, when to revisit)
-
----
-
-## Exit Criteria
-
-- [ ] Custom OTel Collector receiver builds and starts without errors
-- [ ] All `xrpl_*` metrics from server_info, get_counts, peers, validators, fee appear in Prometheus
-- [ ] Metrics update at configured poll interval (default 30s)
-- [ ] 4 new Grafana dashboards operational with data, none reusing a Phase 9 uid
-      (`validator-health`, `peer-quality`, `fee-market`, `job-queue`, `node-health`)
-- [ ] Prometheus alerting rules fire correctly for simulated failure conditions
-- [ ] DEX/AMM collector works when configured (optional — not required for base exit criteria)
-- [ ] Phase 10 validation suite passes with receiver metrics included
-- [ ] Receiver handles xrpld restart/unavailability gracefully (no crash, logs warning, retries)
-- [ ] Documentation complete: receiver README, metric reference, alerting playbook
-- [ ] Go receiver has unit tests with >80% coverage
-- [ ] The 14 not-yet-shipped Grafana alert rules for Phase 7+ parity metrics
-      evaluate correctly (Task 11.12); the other 4 of the 18 already ship in Phase 9
-- [ ] Dual-datasource architecture documented with trade-offs (Task 11.13)

OpenTelemetryPlan/Phase2_taskList.md

@@ -1,240 +0,0 @@
-# Phase 2: RPC Tracing Completion Task List
-
-> **Goal**: Complete RPC tracing coverage with unit tests, Grafana search filters, PathFind instrumentation, and config hardening. Build on the Phase 1c SpanGuard factory foundation to achieve production-quality RPC observability.
->
-> **Scope**: Unit tests for core telemetry, Grafana Tempo search filters, PathFind RPC tracing, config validation (`std::clamp`).
->
-> **Branch**: `pratik/otel-phase2-rpc-tracing` (from `pratik/otel-phase1c-rpc-integration`)
-
-### Related Plan Documents
-
-| Document                                                         | Relevance                                                                                                                        |
-| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| [03-implementation-strategy.md](./03-implementation-strategy.md) | Code structure and instrumentation patterns (replaces the deleted `04-code-samples.md` §4.4.2 / §4.5.3, removed by `d6450631bf`) |
-| [02-design-decisions.md](./02-design-decisions.md)               | W3C Trace Context (§2.5), span attributes (§2.4.2)                                                                               |
-| [06-implementation-phases.md](./06-implementation-phases.md)     | Phase 2 tasks (§6.3), definition of done (§6.11.2)                                                                               |
-
----
-
-## Task 2.1: W3C Trace Context HTTP Header Extraction
-
-**Status**: DEFERRED → Phase 3
-
-**Reason**: W3C context propagation (`traceparent`/`tracestate` headers) requires a consumer — in Phase 2, RPC spans are entirely local to the node. Phase 3 introduces cross-node transaction tracing via protobuf context propagation, which is the first use case for extracted trace context. Implementing it here without a consumer would be dead code.
-
-**Implemented in**: `pratik/otel-phase3-tx-tracing` — `TraceContextPropagator.h/.cpp`
-
----
-
-## Task 2.2: Per-Category Span Creation
-
-**Status**: COMPLETE (superseded by Phase 1c design)
-
-**Original plan**: Add `XRPL_TRACE_PEER` and `XRPL_TRACE_LEDGER` macros.
-
-**Actual implementation**: Phase 1c replaced all tracing macros with the `SpanGuard::span(TraceCategory, prefix, name)` factory pattern. The `TraceCategory` enum (`Rpc`, `Transactions`, `Consensus`, `Peer`, `Ledger`) serves the same conditional-creation purpose without macros. No separate task needed — the factory already supports all categories.
-
----
-
-## Task 2.3: Add shouldTraceLedger() to Telemetry Interface
-
-**Objective**: The `Setup` struct has a `traceLedger` field but there's no corresponding virtual method. Add it for interface completeness.
-
-**What to do**:
-
-- Edit `include/xrpl/telemetry/Telemetry.h`:
-  - Add `virtual bool shouldTraceLedger() const = 0;`
-
-- Update all implementations:
-  - `src/libxrpl/telemetry/Telemetry.cpp` (TelemetryImpl, NullTelemetryOtel)
-  - `src/libxrpl/telemetry/NullTelemetry.cpp` (NullTelemetry)
-
-**Key modified files**:
-
-- `include/xrpl/telemetry/Telemetry.h`
-- `src/libxrpl/telemetry/Telemetry.cpp`
-- `src/libxrpl/telemetry/NullTelemetry.cpp`
-
----
-
-## Task 2.4: Unit Tests for Core Telemetry Infrastructure
-
-**Status**: COMPLETE
-
-**Objective**: Add unit tests for the core telemetry abstractions to validate correctness and catch regressions.
-
-**Implemented**:
-
-- `src/tests/libxrpl/telemetry/TelemetryConfig.cpp`:
-  - Test Setup defaults (all fields have correct initial values)
-  - Test `makeTelemetrySetup` config parser (empty section, full section, edge cases)
-  - Test `samplingRatio` clamping (values outside 0.0-1.0)
-
-- `src/tests/libxrpl/telemetry/SpanGuardFactory.cpp`:
-  - Test null guard methods are safe (setAttribute, setOk, setError, addEvent on null)
-  - Test category span returns null when telemetry disabled
-  - Test child/linked span null when no parent context
-  - Test move construction transfers ownership
-  - Test recordException safe on null guard
-  - Test discard() safe on null guard
-
-- `src/tests/libxrpl/telemetry/main.cpp` — GTest runner
-- `src/tests/libxrpl/CMakeLists.txt` — test target with optional OTel linking
-
----
-
-## Task 2.5: Enhance RPC Span Attributes
-
-**Status**: DEFERRED (low priority)
-
-**Reason**: The high-value attributes (`command`, `version`, `role`, `status`) are already set by Phase 1c. The remaining HTTP transport-level attributes (`http.method`, `net.peer.ip`, `http.status_code`) provide limited additional insight since:
-
-- `http.method` is always POST for JSON-RPC
-- `net.peer.ip` is debug-level info available in logs
-- `duration_ms` is redundant with span duration (OTel captures start/end time natively)
-
-These can be added later if dashboard queries specifically need them. The node health attributes (Task 2.8) provide far more operational value and were prioritized instead.
-
----
-
-## Task 2.6: Build Verification and Performance Baseline
-
-**Objective**: Verify the build succeeds with and without telemetry, and establish a performance baseline.
-
-**What to do**:
-
-1. Build with `telemetry=ON` and verify no compilation errors
-2. Build with `telemetry=OFF` and verify no regressions
-3. Run existing unit tests to verify no breakage
-4. Document any build issues in lessons.md
-
-**Verification Checklist**:
-
-- [ ] `conan install . --build=missing -o telemetry=True` succeeds
-- [ ] `cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -Dtelemetry=ON ..` configures correctly (there is no `default` preset; Conan writes `conan-release`)
-- [ ] Build succeeds with telemetry ON
-- [ ] Build succeeds with telemetry OFF
-- [ ] Existing tests pass with telemetry ON
-- [ ] Existing tests pass with telemetry OFF
-
----
-
-## Task 2.8: RPC Span Attribute Enrichment — Node Health Context
-
-**Status**: DROPPED.
-
-Node health (`amendment_blocked`, `server_state`) is not part of the telemetry surface. Operators consume the same data via the existing `server_info` / `server_state` RPC commands, so duplicating it on traces adds storage and cardinality cost without new value. The OTel C++ SDK 1.18.0 also does not support runtime updates to the resource, ruling out resource-level emission of these dynamic-by-nature flags.
-
----
-
-## Task 2.9: PathFind RPC Instrumentation
-
-**Status**: COMPLETE
-
-**Objective**: Trace the path_find and ripple_path_find RPC handlers to capture request latency and computation cost.
-
-**Spans added**:
-
-- `pathfind.request` — wraps `doPathFind()` and `doRipplePathFind()` RPC handlers
-- `pathfind.compute` — wraps `PathRequest::doUpdate()` (`pathfind_fast` attr)
-- `pathfind.update_all` — wraps `PathRequestManager::updateAll()` on ledger close (`pathfind_ledger_index`, `pathfind_num_requests` attrs; emitted only when active subscriptions exist)
-- `pathfind.discover` — wraps the entire per-source-asset loop in `PathRequest::findPaths()` (`pathfind_search_level`, `pathfind_num_paths` attrs). One span per RPC call instead of N (one per source asset). Trade-off: per-asset breakdown is lost; storage and cardinality bounded.
-
-**Attribute namespacing**: All pathfind attributes use the `pathfind_*` underscore form per the Phase 1c naming-spec rule 5.
-
-**New file**: `src/xrpld/rpc/detail/PathFindSpanNames.h`
-
-**Modified files**:
-
-- `src/xrpld/rpc/handlers/orderbook/PathFind.cpp`
-- `src/xrpld/rpc/handlers/orderbook/RipplePathFind.cpp`
-- `src/xrpld/rpc/detail/PathRequest.cpp`
-- `src/xrpld/rpc/detail/PathRequestManager.cpp`
-- `src/xrpld/rpc/detail/Pathfinder.cpp`
-
----
-
-## Task 2.10: RPC and PathFind Span Attribute Gap Fill
-
-**Status**: COMPLETE
-
-**Objective**: Wire up workflow-identifying attributes that enable filtering and grouping traces by request characteristics without drilling into child spans.
-
-**Attributes added**:
-
-| Span                | Attribute                    | Type   | Source                            |
-| ------------------- | ---------------------------- | ------ | --------------------------------- |
-| `rpc.http_request`  | `request_payload_size`       | int64  | `request.body().size()`           |
-| `rpc.process`       | `is_batch`                   | bool   | `method == "batch"` check         |
-| `rpc.process`       | `batch_size`                 | int64  | `params.size()` (only when batch) |
-| `rpc.ws_message`    | `command`                    | string | `jv[command]` or `jv[method]`     |
-| `rpc.command.*`     | `load_type`                  | string | `context.loadType.label()`        |
-| `pathfind.compute`  | `pathfind_dest_currency`     | string | `to_string(saDstAmount_.asset())` |
-| `pathfind.discover` | `pathfind_num_source_assets` | int64  | `sourceAssets.size()`             |
-
-_Note: `pathfind_dest_amount` was removed — the destination amount is a financial value excluded by the privacy policy (design §2.4.4)._
-
-**New attr keys**: `RpcSpanNames.h` (`isBatch`, `batchSize`, `loadType`), `PathFindSpanNames.h` (`destCurrency`, `numSourceAssets`).
-
-**Modified files**:
-
-- `src/xrpld/rpc/detail/RpcSpanNames.h`
-- `src/xrpld/rpc/detail/PathFindSpanNames.h`
-- `src/xrpld/rpc/detail/ServerHandler.cpp`
-- `src/xrpld/rpc/detail/RPCHandler.cpp`
-- `src/xrpld/rpc/detail/PathRequest.cpp`
-
----
-
-## Summary
-
-| Task | Description                                 | Status              | Notes                                                     |
-| ---- | ------------------------------------------- | ------------------- | --------------------------------------------------------- |
-| 2.1  | W3C Trace Context header extraction         | Deferred → Phase 3  | No consumer in Phase 2; needs cross-node tracing          |
-| 2.2  | Per-category span creation                  | Complete (Phase 1c) | Superseded by TraceCategory enum + SpanGuard              |
-| 2.3  | Add shouldTraceLedger() interface method    | Complete (Phase 1c) | Delivered in Phase 1c base branch                         |
-| 2.4  | Unit tests for core telemetry               | Complete            | TelemetryConfig + SpanGuardFactory tests                  |
-| 2.5  | Enhanced RPC span attributes (HTTP-level)   | Deferred            | Low value; span duration covers timing natively           |
-| 2.6  | Build verification and performance baseline | Complete            | Verified in CI on Phase 1c                                |
-| 2.7  | Grafana Tempo search filters                | Complete            | rpc-command, rpc-status, rpc-role filters                 |
-| 2.8  | RPC span attribute enrichment (node health) | Dropped             | Available via `server_info`/`server_state` RPC            |
-| 2.9  | PathFind RPC instrumentation                | Complete            | request, compute, update_all, discover                    |
-| 2.10 | RPC/PathFind span attribute gap fill        | Complete            | Batch detection, payload size, load cost, pathfind params |
-
-**Delivered in this branch**: Tasks 2.4, 2.7, 2.9, 2.10.
-**Deferred with rationale**: Tasks 2.1 (→Phase 3), 2.5 (low priority).
-**Dropped**: Task 2.8 (node health not duplicated on traces).
-**Superseded**: Task 2.2 (Phase 1c SpanGuard factory covers this).
-
----
-
-## Known Issues / Future Work
-
-### Thread safety of TelemetryImpl::stop() vs startSpan()
-
-`TelemetryImpl::stop()` resets `sdkProvider_` (a `std::shared_ptr`) without
-synchronization. `getTracer()` reads the same member from RPC handler threads.
-This is a data race if any thread calls `startSpan()` concurrently with `stop()`.
-
-**Current mitigation**: `Application::stop()` shuts down `serverHandler_`,
-`overlay_`, and `jobQueue_` before calling `telemetry_->stop()`, so no callers
-remain. See comments in `Telemetry.cpp:stop()` and `Application.cpp`.
-
-**TODO**: Add an `std::atomic<bool> stopped_` flag checked in `getTracer()` to
-make this robust against future shutdown order changes.
-
-### Macro incompatibility: XRPL_TRACE_SPAN vs XRPL_TRACE_SET_ATTR
-
-`XRPL_TRACE_SPAN` and `XRPL_TRACE_SPAN_KIND` declare `_xrpl_guard_` as a bare
-`SpanGuard`, but `XRPL_TRACE_SET_ATTR` and `XRPL_TRACE_EXCEPTION` call
-`_xrpl_guard_.has_value()` which requires `std::optional<SpanGuard>`. Using
-`XRPL_TRACE_SPAN` followed by `XRPL_TRACE_SET_ATTR` in the same scope would
-fail to compile.
-
-**Current mitigation**: No call site currently uses `XRPL_TRACE_SPAN` — all
-production code uses the conditional macros (`XRPL_TRACE_RPC`, `XRPL_TRACE_TX`,
-etc.) which correctly wrap the guard in `std::optional`.
-
-**TODO**: Either make `XRPL_TRACE_SPAN`/`XRPL_TRACE_SPAN_KIND` also wrap in
-`std::optional`, or document that `XRPL_TRACE_SET_ATTR` is only compatible with
-the conditional macros.

OpenTelemetryPlan/Phase3_taskList.md

@@ -1,568 +0,0 @@
-# Phase 3: Transaction Tracing Task List
-
-> **Goal**: Trace the full transaction lifecycle from RPC submission through peer relay, including cross-node context propagation via Protocol Buffer extensions. This is the WALK phase that demonstrates true distributed tracing.
->
-> **Scope**: Protocol Buffer `TraceContext` message, context serialization, PeerImp transaction instrumentation, NetworkOPs processing instrumentation, HashRouter visibility, and multi-node relay context propagation.
->
-> **Branch**: `pratik/otel-phase3-tx-tracing` (from `pratik/otel-phase2-rpc-tracing`)
-
-### Related Plan Documents
-
-| Document                                                                                          | Relevance                                                                                                                                                                                                    |
-| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| [docs/telemetry-runbook.md § Protocol Span Flow](../docs/telemetry-runbook.md#protocol-span-flow) | Authoritative protocol span-flow reference — replaces the deleted `04-code-samples.md` (TraceContext protobuf §4.4.1, PeerImp instrumentation §4.5.1, context serialization §4.4.2), removed by `d6450631bf` |
-| [01-architecture-analysis.md](./01-architecture-analysis.md)                                      | Transaction flow (§1.3), key trace points (§1.6)                                                                                                                                                             |
-| [06-implementation-phases.md](./06-implementation-phases.md)                                      | Phase 3 tasks (§6.4), definition of done (§6.11.3)                                                                                                                                                           |
-| [02-design-decisions.md](./02-design-decisions.md)                                                | Context propagation design (§2.5), attribute schema (§2.4.3)                                                                                                                                                 |
-
----
-
-## Task 3.1: Define TraceContext Protocol Buffer Message
-
-**Objective**: Add trace context fields to the P2P protocol messages so trace IDs can propagate across nodes.
-
-**What to do**:
-
-- Edit `include/xrpl/proto/xrpl.proto` (or `src/xrpld/proto/ripple.proto`, wherever the proto is):
-  - Add `TraceContext` message definition:
-    ```protobuf
-    message TraceContext {
-        bytes trace_id = 1;      // 16-byte trace identifier
-        bytes span_id = 2;       // 8-byte span identifier
-        uint32 trace_flags = 3;  // bit 0 = sampled
-        string trace_state = 4;  // W3C tracestate value
-    }
-    ```
-  - Add `optional TraceContext trace_context = 1001;` to:
-    - `TMTransaction`
-    - `TMProposeSet` (for Phase 4 use)
-    - `TMValidation` (for Phase 4 use)
-  - Use high field numbers (1001+) to avoid conflicts with existing fields
-
-- Regenerate protobuf C++ code
-
-**Key modified files**:
-
-- `include/xrpl/proto/xrpl.proto` (or equivalent)
-
-**Reference**:
-
-- `04-code-samples.md` §4.4.1 (TraceContext message definition) was deleted by
-  `d6450631bf`; the live definition is `include/xrpl/proto/xrpl.proto:101`
-  (`message TraceContext`), attached as field `1001` on the relevant messages
-- [02-design-decisions.md §2.5.2](./02-design-decisions.md) — Protocol buffer context propagation design
-
----
-
-## Task 3.2: Implement Protobuf Context Serialization
-
-**Objective**: Create utilities to serialize/deserialize OTel trace context to/from protobuf `TraceContext` messages.
-
-**What to do**:
-
-- Create `include/xrpl/telemetry/TraceContextPropagator.h` (extend from Phase 2 if exists, or add protobuf methods):
-  - Add protobuf-specific methods:
-    - `static Context extractFromProtobuf(protocol::TraceContext const& proto)` — reconstruct OTel context from protobuf fields
-    - `static void injectToProtobuf(Context const& ctx, protocol::TraceContext& proto)` — serialize current span context into protobuf fields
-  - Both methods guard behind `#ifdef XRPL_ENABLE_TELEMETRY`
-
-- Create/extend `src/libxrpl/telemetry/TraceContextPropagator.cpp`:
-  - Implement extraction: read trace_id (16 bytes), span_id (8 bytes), trace_flags from protobuf, construct `SpanContext`, wrap in `Context`
-  - Implement injection: get current span from context, serialize its TraceId, SpanId, and TraceFlags into protobuf fields
-
-**Key new/modified files**:
-
-- `include/xrpl/telemetry/TraceContextPropagator.h`
-- `src/libxrpl/telemetry/TraceContextPropagator.cpp`
-
-**Reference**:
-
-- `04-code-samples.md` §4.4.2 (full extract/inject implementation) was deleted by
-  `d6450631bf`. As shipped there is **no**
-  `src/libxrpl/telemetry/TraceContextPropagator.cpp`; extract/inject live on
-  `SpanGuard` (`include/xrpl/telemetry/SpanGuard.h:467` extract, `:480-491`
-  `injectCurrentContextToProtobuf`, implemented in
-  `src/libxrpl/telemetry/SpanGuard.cpp`) with the protocol-layer wrappers in
-  `src/xrpld/telemetry/PropagationHelpers.h:52` (`injectSpanContext`)
-
----
-
-## Task 3.3: Instrument PeerImp Transaction Handling
-
-**Objective**: Add trace spans to the peer-level transaction receive and relay path.
-
-**What to do**:
-
-- Edit `src/xrpld/overlay/detail/PeerImp.cpp`:
-  - In `onMessage(TMTransaction)` / `handleTransaction()`:
-    - Extract parent trace context from incoming `TMTransaction::trace_context` field (if present)
-    - Create `tx.receive` span as child of extracted context (or new root if none)
-    - Set attributes: `tx_hash`, `peer_id`, `tx_status`
-    - On HashRouter suppression (duplicate): set `suppressed=true`, add `tx.duplicate` event
-    - Wrap validation call with child span `tx.validate`
-    - Wrap relay with `tx.relay` span
-  - When relaying to peers:
-    - Inject current trace context into outgoing `TMTransaction::trace_context`
-    - Set `relay_count` attribute
-
-- Use `SpanGuard::span(TraceCategory::Transactions, "tx", "receive")` factory
-  (Phase 1c replaced macros with the SpanGuard factory pattern)
-
-> **Note**: The `tx.receive` guard is `.detached()` before being moved into the
-> `RcvCheckTx` job so its Scope is popped on the peer thread, not leaked to the
-> worker (else later peer messages would inherit this transaction's trace).
-
-**Key modified files**:
-
-- `src/xrpld/overlay/detail/PeerImp.cpp`
-
-**Reference**:
-
-- [docs/telemetry-runbook.md § Protocol Span Flow](../docs/telemetry-runbook.md#protocol-span-flow)
-  — the authoritative `tx.receive` / relay span-flow reference; replaces
-  `04-code-samples.md` §4.5.1, deleted by `d6450631bf`
-- [01-architecture-analysis.md §1.3](./01-architecture-analysis.md) — Transaction flow diagram
-- [01-architecture-analysis.md §1.6](./01-architecture-analysis.md) — tx.receive trace point
-
----
-
-## Task 3.4: Instrument NetworkOPs Transaction Processing
-
-**Objective**: Trace the transaction processing pipeline in NetworkOPs, covering both sync and async paths.
-
-**What to do**:
-
-- Edit `src/xrpld/app/misc/NetworkOPs.cpp`:
-  - In `processTransaction()`:
-    - Create `tx.process` span
-    - Set attributes: `tx_hash`, `tx_type`, `local` (whether from RPC or peer)
-    - Record whether sync or async path is taken
-    - `.detached()` the guard before storing it in `TransactionStatus::span`,
-      since it is applied on a batch worker thread — this pops the Scope on the
-      origin thread and stops later work inheriting this transaction's trace
-
-  - In `doTransactionAsync()`:
-    - Capture parent context before queuing
-    - Create `tx.queue` span with queue depth attribute
-    - Add event when transaction is dequeued for processing
-
-  - In `doTransactionSync()`:
-    - Create `tx.process_sync` span
-    - Record result (applied, queued, rejected)
-
-**Key modified files**:
-
-- `src/xrpld/app/misc/NetworkOPs.cpp`
-
-**Reference**:
-
-- [01-architecture-analysis.md §1.6](./01-architecture-analysis.md) — tx.validate and tx.process trace points
-- [02-design-decisions.md §2.4.3](./02-design-decisions.md) — Transaction attribute schema
-
----
-
-## Task 3.5: Instrument HashRouter for Dedup Visibility
-
-**Objective**: Make transaction deduplication visible in traces by recording HashRouter decisions as span attributes/events.
-
-**What to do**:
-
-- Edit `src/xrpld/overlay/detail/PeerImp.cpp` (in handleTransaction):
-  - After calling `HashRouter::shouldProcess()` or `addSuppressionPeer()`:
-    - Record `suppressed` attribute (true/false)
-    - Record `tx_flags` showing current HashRouter state (SAVED, TRUSTED, etc.)
-    - Add `tx.first_seen` or `tx.duplicate` event
-
-- This is NOT a modification to HashRouter itself — just recording its decisions as span attributes in the existing PeerImp instrumentation from Task 3.3.
-
-**Key modified files**:
-
-- `src/xrpld/overlay/detail/PeerImp.cpp` (same changes as 3.3, logically grouped)
-
----
-
-## Task 3.6: Context Propagation in Transaction Relay
-
-**Status**: COMPLETE (transaction relay). Consensus proposal/validation
-propagation is deferred to Phase 4 — see "Planned (Phase 4)" below.
-
-**Objective**: Ensure trace context flows correctly when transactions are relayed between peers, creating linked spans across nodes.
-
-**What was done**:
-
-- **TX send side**: `NetworkOPs::apply()` now injects the tx.process span's trace
-  context into the outgoing `TMTransaction` protobuf before relay, using
-  `telemetry::injectSpanContext()`. The receiving node's `txReceiveSpan()` (already
-  wired in PeerImp) extracts the parent span_id and creates the tx.receive span
-  as a child of the sender's tx.process span.
-
-- **Edge cases**: Missing trace context (older peers) degrades gracefully to
-  standalone spans. Invalid/corrupted context is treated as absent. Trace
-  flags are propagated and respected.
-
-**New infrastructure**:
-
-- `SpanGuard::getTraceBytes()` — extracts raw trace_id/span_id/trace_flags
-  from a span without exposing OTel types. Safe to call from any thread.
-- `PropagationHelpers.h` — `injectSpanContext(SpanGuard&, proto)` bridge
-  between SpanGuard and protobuf TraceContext.
-- `TraceContextPropagator.h` — `injectToProtobuf(ctx, proto)` for
-  same-thread injection via OTel RuntimeContext.
-
-**Key modified files**:
-
-- `src/xrpld/app/misc/NetworkOPs.cpp` — tx relay injection
-- `include/xrpl/telemetry/SpanGuard.h` — `TraceBytes` struct, `getTraceBytes()`
-- `src/libxrpl/telemetry/SpanGuard.cpp` — `getTraceBytes()` implementation
-- `src/xrpld/telemetry/PropagationHelpers.h` — inject helpers (new file)
-
-**Planned (Phase 4 — not in this PR)**:
-
-The consensus proposal/validation propagation below is Phase 4 scope and is
-not implemented on this branch. It is listed here only to record the intended
-design.
-
-- **Proposal send/receive**: `RCLConsensus::Adaptor::propose()` injects the
-  current thread's active span context into the `TMProposeSet` protobuf via
-  `telemetry::injectToProtobuf()`. PeerImp creates a
-  `consensus.proposal.receive` span that extracts the sender's trace context
-  as parent (via `ConsensusReceiveTracing.h`).
-
-- **Validation send/receive**: `RCLConsensus::Adaptor::validate()` injects
-  the current thread's active span context into the `TMValidation` protobuf.
-  PeerImp creates a `consensus.validation.receive` span that extracts the
-  sender's trace context as parent.
-
-- Planned files: `src/xrpld/app/consensus/RCLConsensus.cpp` (send injection),
-  `src/xrpld/overlay/detail/PeerImp.cpp` (receive spans),
-  `src/xrpld/telemetry/ConsensusReceiveTracing.h` (receive span helpers,
-  new file).
-
-**Reference**:
-
-- [02-design-decisions.md §2.5](./02-design-decisions.md) — Context propagation design
-- Relay context injection pattern: `04-code-samples.md` §4.5.1 was deleted by
-  `d6450631bf`; the live pattern is `injectSpanContext()` in
-  `src/xrpld/telemetry/PropagationHelpers.h:52`, with the flow documented in
-  [docs/telemetry-runbook.md § Protocol Span Flow](../docs/telemetry-runbook.md#protocol-span-flow)
-
----
-
-## Task 3.7: Build Verification and Testing
-
-**Objective**: Verify all Phase 3 changes compile and work correctly.
-
-**What to do**:
-
-1. Build with `telemetry=ON` — verify no compilation errors
-2. Build with `telemetry=OFF` — verify no regressions
-3. Run existing unit tests
-4. Verify protobuf regeneration produces correct C++ code
-5. Document any issues encountered
-
-**Verification Checklist**:
-
-- [ ] Protobuf changes generate valid C++
-- [ ] Build succeeds with telemetry ON
-- [ ] Build succeeds with telemetry OFF
-- [ ] Existing tests pass
-- [ ] No undefined symbols from new telemetry calls
-
----
-
-## Task 3.8: Transaction Span Peer Version Attribute
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity) — adds peer version context inspired by the community [xrpl-validator-dashboard](https://github.com/realgrapedrop/xrpl-validator-dashboard).
->
-> **Upstream**: Phase 2 (RPC span infrastructure must exist).
-> **Downstream**: Phase 10 (validation checks for this attribute).
-
-**Objective**: Add the relaying peer's xrpld version to `tx.receive` spans so operators can correlate transaction issues with peer version mismatches during network upgrades.
-
-**What to do**:
-
-- Edit `src/xrpld/overlay/detail/PeerImp.cpp`:
-  - In the `tx.receive` span block (after existing `peer_id` setAttribute call):
-    - Add `peer_version` (string) — from `this->getVersion()`
-    - Only set if `getVersion()` returns a non-empty string (avoid empty-string attributes)
-
-**New span attribute**:
-
-| Attribute      | Type   | Source               | Example         |
-| -------------- | ------ | -------------------- | --------------- |
-| `peer_version` | string | `peer->getVersion()` | `"xrpld-2.4.0"` |
-
-**Rationale**: Transaction relay is where version mismatches cause subtle serialization or validation bugs. Tracing "this tx came from a v2.3.0 peer" helps diagnose compatibility issues. The community dashboard tracks peer versions externally; this brings version awareness into the trace itself.
-
-**Key modified files**:
-
-- `src/xrpld/overlay/detail/PeerImp.cpp`
-
-**Exit Criteria**:
-
-- [ ] `tx.receive` spans carry `peer_version` attribute with a non-empty version string
-- [ ] Attribute is omitted (not set to empty string) when `getVersion()` returns empty
-- [ ] Attribute visible in Tempo trace detail view
-
----
-
-## Task 3.9: Deterministic Transaction Trace ID
-
-> **Upstream**: Task 3.2 (protobuf serialization), Task 3.3 (PeerImp span exists).
-> **Downstream**: Phase 10 (workload validation can query by tx hash directly).
-> **Pattern**: Mirrors the consensus deterministic trace ID in Phase 4a
-> (`createDeterministicContext` in `RCLConsensus.cpp`), adapted for transactions.
-
-**Objective**: Derive the trace_id for transaction spans deterministically from the
-transaction hash so that all nodes handling the same transaction independently produce
-spans under the same trace_id — regardless of whether protobuf context propagation
-succeeds.
-
-**Why**: The current approach creates spans with random trace_ids and relies entirely
-on protobuf `TraceContext` propagation to link them. If any hop in the relay chain
-drops the context (older peers, message corruption, mixed-version networks), the trace
-splits and downstream spans become impossible to find. With deterministic trace_ids,
-correlation is guaranteed because every node derives the same trace_id from the same
-`txID`.
-
-**Approach — deterministic trace_id + protobuf span_id propagation**:
-
-1. Derive `trace_id = txHash[0:16]` (first 16 bytes of the 32-byte transaction hash).
-2. Generate a random 8-byte `span_id` per node (each node's span is unique within
-   the shared trace).
-3. Create the span under this deterministic context as parent.
-4. **Additionally**, if protobuf `TraceContext` is present in the incoming
-   `TMTransaction` message, extract the sender's `span_id` and use it as the span's
-   parent — this preserves parent-child ordering in the trace tree.
-5. If protobuf context is absent (older peer, first hop), the span still has the
-   correct deterministic `trace_id` — it appears as a sibling root in the same trace
-   rather than being lost.
-
-This gives the best of both worlds: guaranteed cross-node correlation via deterministic
-`trace_id`, plus parent-child relay ordering via protobuf `span_id` when available.
-
-**What to do**:
-
-- Create `createDeterministicTxContext(uint256 const& txHash)` utility function:
-  - Location: shared header or file-local in `PeerImp.cpp` and `NetworkOPs.cpp`
-    (or a shared telemetry utility if both need it).
-  - Pattern: identical to `createDeterministicContext(uint256 const& ledgerId)` in
-    `RCLConsensus.cpp` — take `txHash[0:16]` as trace_id, random span_id via
-    `default_prng()`, sampled flag set, `remote=false`.
-  - Guard behind `#ifdef XRPL_ENABLE_TELEMETRY`.
-
-  ```cpp
-  opentelemetry::context::Context
-  createDeterministicTxContext(uint256 const& txHash)
-  {
-      namespace trace = opentelemetry::trace;
-
-      // First 16 bytes of the 32-byte tx hash as trace ID.
-      trace::TraceId traceId(
-          opentelemetry::nostd::span<uint8_t const, 16>(txHash.data(), 16));
-
-      // Random span_id so each node's span is unique within the trace.
-      uint8_t spanIdBytes[8];
-      auto const rval = default_prng()();
-      std::memcpy(spanIdBytes, &rval, sizeof(spanIdBytes));
-      trace::SpanId spanId(
-          opentelemetry::nostd::span<uint8_t const, 8>(spanIdBytes, 8));
-
-      trace::SpanContext syntheticCtx(
-          traceId, spanId, trace::TraceFlags(1), /* remote = */ false);
-
-      return opentelemetry::context::Context{}.SetValue(
-          trace::kSpanKey,
-          opentelemetry::nostd::shared_ptr<trace::Span>(
-              new trace::DefaultSpan(syntheticCtx)));
-  }
-  ```
-
-- Edit `src/xrpld/overlay/detail/PeerImp.cpp` — restructure `handleTransaction()`:
-  - **Move span creation after deserialization** (txID must be known first):
-    1. Deserialize `STTx` and get `txID` (existing code at line ~1382).
-    2. Create deterministic parent context: `auto detCtx = createDeterministicTxContext(txID)`.
-    3. If `m->has_trace_context()`: extract protobuf context via `extractFromProtobuf()`,
-       **combine** with deterministic trace_id — use the protobuf span_id as parent
-       to preserve relay ordering, but override trace_id with the deterministic one.
-    4. If no protobuf context: create span under `detCtx` directly.
-    5. Set all existing attributes (`hash`, `peerId`, `peerVersion`, `suppressed`, etc.).
-
-  - **Combining deterministic trace_id with protobuf parent span_id**:
-    When both are available, construct a synthetic `SpanContext` with:
-    - `trace_id` = `txHash[0:16]` (deterministic)
-    - `span_id` = extracted from protobuf (sender's span_id → becomes parent)
-    - `trace_flags` = from protobuf
-    - `remote` = true (came from another node)
-
-    ```cpp
-    // Pseudo-code for the combined context:
-    auto detTraceId = trace::TraceId(txHash.data(), 16);
-    auto remoteSpanId = /* from extractFromProtobuf */;
-    auto remoteFlags = /* from extractFromProtobuf */;
-
-    trace::SpanContext combinedCtx(
-        detTraceId, remoteSpanId, remoteFlags, /* remote = */ true);
-    // Use as parent context for the new span.
-    ```
-
-- Edit `src/xrpld/app/misc/NetworkOPs.cpp` — update `processTransaction()`:
-  - `transaction->getID()` is already available at the top of the function.
-  - Create deterministic parent context from `txID`.
-  - Create `tx.process` span under this context.
-  - No protobuf context to extract here (NetworkOPs is intra-node), so
-    deterministic context alone is sufficient.
-
-- Add `trace_strategy` attribute to spans:
-  - Add `inline constexpr auto traceStrategy = "trace_strategy";`
-    to `TxSpanNames.h`.
-  - Set on each tx span: `span.setAttribute(tx_span::attr::traceStrategy, "deterministic")`.
-
-**Key new/modified files**:
-
-- `src/xrpld/overlay/detail/PeerImp.cpp` — restructured span creation
-- `src/xrpld/app/misc/NetworkOPs.cpp` — deterministic context for tx.process
-- `src/xrpld/telemetry/TxSpanNames.h` — new `traceStrategy` attribute constant
-- New or shared utility for `createDeterministicTxContext()` (location TBD: could be
-  a shared header like `include/xrpl/telemetry/DeterministicContext.h`, or file-local
-  if only used in two places)
-
-**Interaction with existing tasks**:
-
-- **Task 3.3 (PeerImp instrumentation)**: The span creation in `handleTransaction()`
-  must be restructured — the span currently starts before `txID` is known. This task
-  moves it after deserialization.
-- **Task 3.6 (Relay context propagation)**: Protobuf injection at the relay site
-  remains the same — `injectToProtobuf()` serializes the current span's `span_id`.
-  The receiver extracts it and combines with the deterministic `trace_id`.
-- **Phase 4a (Consensus deterministic trace ID)**: This task follows the same pattern.
-  Consider extracting a shared utility (e.g., `createDeterministicContext(uint256)`)
-  that both consensus and transaction tracing use.
-
-**Exit Criteria**:
-
-- [ ] `tx.receive` and `tx.process` spans have deterministic trace_id = `txHash[0:16]`
-- [ ] All nodes handling the same transaction produce spans under the same trace_id
-- [x] Protobuf `span_id` propagation still works when available (parent-child ordering)
-- [ ] Missing protobuf context (old peer) degrades gracefully to sibling spans, not lost traces
-- [ ] `trace_strategy` attribute set to `"deterministic"` on all tx spans
-- [ ] Trace queryable by tx hash (truncate hash → trace_id → direct lookup in Tempo)
-
-**Deliverables implemented (not in original plan)**:
-
-- **`SpanGuard::txSpan()` factory method** (`include/xrpl/telemetry/SpanGuard.h`):
-  Two overloads for creating transaction spans with deterministic trace IDs:
-  - `txSpan(category, group, name, txHash)` — standalone span (deterministic
-    trace_id from `txHash[0:16]`, no parent span_id).
-  - `txSpan(category, group, name, txHash, parentCtx)` — child span (deterministic
-    trace_id combined with protobuf-extracted parent span_id for relay ordering).
-
-- **`TxTracing.h` helper functions** (`src/xrpld/telemetry/TxTracing.h`):
-  File-local helpers that wrap `SpanGuard::txSpan()` for the two main PeerImp call
-  sites:
-  - `txReceiveSpan(txHash, parentCtx)` — creates `tx.receive` span with
-    deterministic trace_id and optional protobuf parent context.
-  - `txProcessSpan(txHash)` — creates `tx.process` span with deterministic
-    trace_id only (no protobuf parent, used intra-node).
-  - **Note**: `TxTracing.h` includes `xrpl.pb.h` unconditionally (outside
-    `#ifdef XRPL_ENABLE_TELEMETRY`) because `protocol::TMTransaction` appears in
-    the function signatures regardless of telemetry build mode.
-
----
-
-## Task 3.10: TxQ Instrumentation
-
-**Status**: COMPLETE
-
-**Objective**: Trace the transaction queue lifecycle — enqueue decisions, direct apply, batch clear, ledger-close accept loop, per-tx apply, and cleanup.
-
-**Spans added**:
-
-- `txq.enqueue` — wraps `TxQ::apply()` with tx_hash attribute
-- `txq.apply_direct` — wraps `TxQ::tryDirectApply()` fast-path
-- `txq.batch_clear` — wraps `TxQ::tryClearAccountQueueUpThruTx()`
-- `txq.accept` — wraps `TxQ::accept()` ledger-close dequeue with queue_size attr
-- `txq.accept_tx` — per-tx span inside accept loop with tx_hash, ter_code,
-  retries_remaining attributes
-- `txq.cleanup` — wraps `TxQ::processClosedLedger()` with ledger_seq attribute
-
-**New file**: `src/xrpld/app/misc/detail/TxQSpanNames.h`
-
-**Modified file**: `src/xrpld/app/misc/detail/TxQ.cpp`
-
----
-
-## Task 3.11: TX and TxQ Span Attribute Gap Fill
-
-**Status**: COMPLETE
-
-**Objective**: Add workflow-identifying attributes to transaction spans so operators can filter by transaction type and see outcomes without off-chain correlation.
-
-**Attributes added**:
-
-| Span              | Attribute            | Type   | Source                                                              |
-| ----------------- | -------------------- | ------ | ------------------------------------------------------------------- |
-| `tx.process`      | `tx_type`            | string | `TxFormats::getInstance().findByType(stx->getTxnType())->getName()` |
-| `tx.process`      | `fee`                | int64  | `stx->getFieldAmount(sfFee).xrp().drops()`                          |
-| `tx.process`      | `sequence`           | int64  | `stx->getSeqProxy().value()`                                        |
-| `tx.process`      | `ter_result`         | string | `transToken(e.result)` (set after batch application)                |
-| `tx.process`      | `applied`            | bool   | `e.applied` (set after batch application)                           |
-| `tx.receive`      | `tx_type`            | string | `TxFormats::getInstance().findByType(stx->getTxnType())->getName()` |
-| `txq.enqueue`     | `tx_type`            | string | same pattern as above                                               |
-| `txq.enqueue`     | `txq_status`         | string | `queued` / `applied_direct` / `applied` / `rejected`                |
-| `txq.enqueue`     | `fee_level_paid`     | int64  | `getFeeLevelPaid(view, *tx).value()`                                |
-| `txq.enqueue`     | `required_fee_level` | int64  | `getRequiredFeeLevel(...).value()`                                  |
-| `txq.batch_clear` | `num_cleared`        | int64  | queued txs cleared ahead of the applying tx                         |
-| `txq.cleanup`     | `expired_count`      | int64  | entries dropped for passed `LastLedgerSequence`                     |
-| `txq.accept_tx`   | `txq_status`         | string | `applied` / `failed` / `retried`                                    |
-| `txq.accept`      | `ledger_changed`     | bool   | set at end of accept loop                                           |
-
-**New attr keys**: `TxSpanNames.h` (`txType`, `fee`, `sequence`, `terResult`, `applied`), `TxQSpanNames.h` (`txType`).
-
-**Modified files**:
-
-- `src/xrpld/telemetry/TxSpanNames.h`
-- `src/xrpld/app/misc/detail/TxQSpanNames.h`
-- `src/xrpld/app/misc/NetworkOPs.cpp`
-- `src/xrpld/overlay/detail/PeerImp.cpp`
-- `src/xrpld/app/misc/detail/TxQ.cpp`
-
----
-
-## Summary
-
-| Task | Description                         | New Files | Modified Files | Depends On |
-| ---- | ----------------------------------- | --------- | -------------- | ---------- |
-| 3.1  | TraceContext protobuf message       | 0         | 1              | Phase 2    |
-| 3.2  | Protobuf context serialization      | 1-2       | 0              | 3.1        |
-| 3.3  | PeerImp transaction instrumentation | 0         | 1              | 3.2        |
-| 3.4  | NetworkOPs transaction processing   | 0         | 1              | Phase 2    |
-| 3.5  | HashRouter dedup visibility         | 0         | 1              | 3.3        |
-| 3.6  | Relay context propagation           | 0         | 1-2            | 3.3, 3.5   |
-| 3.7  | Build verification and testing      | 0         | 0              | 3.1-3.6    |
-| 3.8  | TX span peer version attribute      | 0         | 1              | 3.3        |
-| 3.9  | Deterministic transaction trace ID  | 0-1       | 3              | 3.2, 3.3   |
-| 3.10 | TxQ instrumentation (6 spans)       | 1         | 1              | 3.4        |
-| 3.11 | TX/TxQ span attribute gap fill      | 0         | 5              | 3.3, 3.10  |
-
-**Parallel work**: Tasks 3.1 and 3.4 can start in parallel. Task 3.2 depends on 3.1. Tasks 3.3 and 3.5 depend on 3.2. Task 3.6 depends on 3.3 and 3.5. Task 3.8 depends on 3.3 (span must exist). Task 3.9 depends on 3.2 and 3.3. Task 3.10 depends on 3.4 (tx.process span must exist).
-
-**Exit Criteria** (from [06-implementation-phases.md §6.11.3](./06-implementation-phases.md)):
-
-- [x] Transaction traces span across nodes
-- [x] Trace context in Protocol Buffer messages
-- [ ] HashRouter deduplication visible in traces
-- [ ] <5% overhead on transaction throughput
-- [x] Deterministic trace_id: same trace_id for same tx across all nodes
-- [x] Protobuf span_id propagation preserves parent-child ordering when available
-
----
-
-## Known Issues / Future Work
-
-### Unused trace_state proto field
-
-The `TraceContext.trace_state` field (field 4) in `xrpl.proto` is reserved for
-W3C `tracestate` vendor-specific key-value pairs but is not read or written by
-`TraceContextPropagator`. Wire it when cross-vendor trace propagation is needed.
-No wire cost since proto `optional` fields are zero-cost when absent.

OpenTelemetryPlan/Phase5_IntegrationTest_taskList.md

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

OpenTelemetryPlan/Phase5_taskList.md

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

OpenTelemetryPlan/Phase7_taskList.md

@@ -1,599 +0,0 @@
-# Phase 7: Native OTel Metrics Migration — Task List
-
-> **Goal**: Replace `StatsDCollector` with a native OpenTelemetry Metrics SDK implementation behind the existing `beast::insight::Collector` interface, eliminating the StatsD UDP dependency.
->
-> **Scope**: New `OTelCollectorImpl` class, `CollectorManager` config change, OTel Collector pipeline update, Grafana dashboard metric name migration, integration tests.
->
-> **Branch**: `pratik/otel-phase7-native-metrics` (from `pratik/otel-phase6-statsd`)
-
-### Related Plan Documents
-
-| Document                                                             | Relevance                                                       |
-| -------------------------------------------------------------------- | --------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)         | Phase 7 plan: motivation, architecture, exit criteria (§6.8)    |
-| [02-design-decisions.md](./02-design-decisions.md)                   | Collector interface design, beast::insight coexistence strategy |
-| [05-configuration-reference.md](./05-configuration-reference.md)     | `[insight]` and `[telemetry]` config sections                   |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Complete metric inventory that must be preserved                |
-
----
-
-## Task 7.1: Add OTel Metrics SDK to Build Dependencies
-
-**Objective**: Enable the OTel C++ Metrics SDK components in the build system.
-
-**What to do**:
-
-- Edit `conanfile.py`:
-  - Add OTel metrics SDK components to the dependency list when `telemetry=True`
-  - Components needed: `opentelemetry-cpp::metrics`, `opentelemetry-cpp::otlp_http_metric_exporter`
-
-- Edit `CMakeLists.txt` (telemetry section):
-  - Link `opentelemetry::metrics` and `opentelemetry::otlp_http_metric_exporter` targets
-
-**Key modified files**:
-
-- `conanfile.py`
-- `CMakeLists.txt` (or the relevant telemetry cmake target)
-
-**Reference**: [05-configuration-reference.md §5.3](./05-configuration-reference.md) — CMake integration
-
----
-
-## Task 7.2: Implement OTelCollector Class
-
-**Objective**: Create the core `OTelCollector` implementation that maps beast::insight instruments to OTel Metrics SDK instruments.
-
-**What to do**:
-
-- Create `include/xrpl/beast/insight/OTelCollector.h`:
-  - Public factory: `static std::shared_ptr<OTelCollector> New(std::string const& endpoint, std::string const& prefix, beast::Journal journal)`
-  - Derives from `StatsDCollector` (or directly from `Collector` — TBD based on shared code)
-
-- Create `src/libxrpl/beast/insight/OTelCollector.cpp` (~400-500 lines):
-  - **OTelCounterImpl**: Wraps `opentelemetry::metrics::Counter<int64_t>`. `increment(amount)` calls `counter->Add(amount)`.
-  - **OTelGaugeImpl**: Uses `opentelemetry::metrics::ObservableGauge<uint64_t>` with an async callback. `set(value)` stores value atomically; callback reads it during collection.
-  - **OTelMeterImpl**: Wraps `opentelemetry::metrics::Counter<uint64_t>`. `increment(amount)` calls `counter->Add(amount)`. Semantically identical to Counter but unsigned.
-  - **OTelEventImpl**: Wraps `opentelemetry::metrics::Histogram<double>`. `notify()` calls `histogram->Record(value.count())`. Declares its unit from `beast::insight::Unit`, which is what selects its bucket ladder: the histogram views in `Telemetry.cpp` match on unit, so a `ms` instrument gets the millisecond ladder and a `By` instrument the byte ladder. Bucket edges live in `include/xrpl/telemetry/HistogramBuckets.h` — do not restate them here. The millisecond ladder must contain every representable edge of the collector's spanmetrics ladder and may extend above it (jobs outlive spans); `.github/scripts/telemetry/check_bucket_parity.py` enforces that. An earlier version of this line specified `[1, 5, 10, 25, 50, 100, 250, 500, 1000, 5000] ms` as "matching SpanMetrics" — true when written, then silently false once the collector ladder was extended on its own, which capped every quantile above 5s at a flat 5000.
-  - **OTelHookImpl**: Stores handler function. Called during periodic metric collection (same 1s pattern via PeriodicMetricReader).
-  - **OTelCollectorImp**: Main class.
-    - Creates `MeterProvider` with `PeriodicMetricReader` (1s export interval)
-    - Creates `OtlpHttpMetricExporter` pointing to `[telemetry]` endpoint
-    - Sets resource attributes (service.name, service.instance.id) matching trace exporter
-    - Implements all `make_*()` factory methods
-    - Prefixes metric names with `[insight] prefix=` value
-
-- Guard all OTel SDK includes with `#ifdef XRPL_ENABLE_TELEMETRY` to compile to `NullCollector` equivalents when telemetry disabled.
-
-**Key new files**:
-
-- `include/xrpl/beast/insight/OTelCollector.h`
-- `src/libxrpl/beast/insight/OTelCollector.cpp`
-
-**Key patterns to follow**:
-
-- Match `StatsDCollector.cpp` structure: private impl classes, intrusive list for metrics, strand-based thread safety
-- Match existing telemetry code style from `src/libxrpl/telemetry/Telemetry.cpp`
-- Use RAII for MeterProvider lifecycle (shutdown on destructor)
-
-**Reference**: [03-implementation-strategy.md](./03-implementation-strategy.md) —
-code style and patterns (`04-code-samples.md` was deleted by `d6450631bf`)
-
----
-
-## Task 7.3: Update CollectorManager
-
-**Objective**: Add `server=otel` config option to route metric creation to the new OTel backend.
-
-**What to do**:
-
-- Edit `src/xrpld/app/main/CollectorManager.cpp`:
-  - In the constructor, add a third branch after `server == "statsd"`:
-    ```cpp
-    else if (server == "otel")
-    {
-        // Read endpoint from [telemetry] section
-        auto const endpoint = get(telemetryParams, "endpoint",
-            "http://localhost:4318/v1/metrics");
-        std::string const& prefix(get(params, "prefix"));
-        collector_ = beast::insight::OTelCollector::New(
-            endpoint, prefix, journal);
-    }
-    ```
-  - This requires access to the `[telemetry]` config section — may need to pass it as a parameter or read from Application config.
-
-- Edit `src/xrpld/app/main/CollectorManager.h`:
-  - Add `#include <xrpl/beast/insight/OTelCollector.h>`
-
-**Key modified files**:
-
-- `src/xrpld/app/main/CollectorManager.cpp`
-- `src/xrpld/app/main/CollectorManager.h`
-
----
-
-## Task 7.4: Update OTel Collector Configuration
-
-**Objective**: Add a metrics pipeline to the OTLP receiver and remove the StatsD receiver dependency.
-
-**What to do**:
-
-- Edit `docker/telemetry/otel-collector-config.yaml`:
-  - Remove `statsd` receiver (no longer needed when `server=otel`)
-  - Add metrics pipeline under `service.pipelines`:
-    ```yaml
-    metrics:
-      receivers: [otlp, spanmetrics]
-      processors: [batch]
-      exporters: [prometheus]
-    ```
-  - The OTLP receiver already listens on :4318 — it just needs to be added to the metrics pipeline receivers.
-  - Keep `spanmetrics` connector in the metrics pipeline so span-derived RED metrics continue working.
-
-- Edit `docker/telemetry/docker-compose.yml`:
-  - Remove UDP :8125 port mapping from otel-collector service
-  - Update xrpld service config: change `[insight] server=statsd` to `server=otel`
-
-**Key modified files**:
-
-- `docker/telemetry/otel-collector-config.yaml`
-- `docker/telemetry/docker-compose.yml`
-
-**Note**: Keep a commented-out `statsd` receiver block for operators who need backward compatibility.
-
----
-
-## Task 7.5: Preserve Metric Names in Prometheus
-
-**Objective**: Ensure existing Grafana dashboards continue working with identical metric names.
-
-**What to do**:
-
-- In `OTelCollector.cpp`, construct OTel instrument names to match existing Prometheus metric names:
-  - beast::insight `make_gauge("LedgerMaster", "Validated_Ledger_Age")` → OTel instrument name: `xrpld_LedgerMaster_Validated_Ledger_Age`
-  - The prefix + group + name concatenation must produce the same string as `StatsDCollector`'s format
-  - Use underscores as separators (matching StatsD convention)
-
-- Verify in integration test that key Prometheus queries still return data:
-  - `xrpld_LedgerMaster_Validated_Ledger_Age`
-  - `xrpld_Peer_Finder_Active_Inbound_Peers`
-  - `xrpld_rpc_requests`
-
-**Key consideration**: OTel Prometheus exporter may normalize metric names differently than StatsD receiver. Test this early (Task 7.2) and adjust naming strategy if needed. The OTel SDK's Prometheus exporter adds `_total` suffix to counters and converts dots to underscores — match existing conventions.
-
----
-
-## Task 7.6: Update Grafana Dashboards
-
-**Objective**: Update the 3 StatsD dashboards if any metric names change due to OTLP export format differences.
-
-**What to do**:
-
-- If Task 7.5 confirms metric names are preserved exactly, no dashboard changes needed.
-- If OTLP export produces different names (e.g., `_total` suffix on counters), update:
-  - `docker/telemetry/grafana/dashboards/statsd-node-health.json`
-  - `docker/telemetry/grafana/dashboards/statsd-network-traffic.json`
-  - `docker/telemetry/grafana/dashboards/statsd-rpc-pathfinding.json`
-- Rename dashboard titles from "StatsD" to "System Metrics" or similar (since they're no longer StatsD-sourced).
-
-**Key modified files**:
-
-- `docker/telemetry/grafana/dashboards/statsd-*.json` (3 files, conditionally)
-
----
-
-## Task 7.7: Update Integration Tests
-
-**Objective**: Verify the full OTLP metrics pipeline end-to-end.
-
-**What to do**:
-
-- Edit `docker/telemetry/integration-test.sh`:
-  - Update test config to use `[insight] server=otel`
-  - Verify metrics arrive in Prometheus via OTLP (not StatsD)
-  - Add check that StatsD receiver is no longer required
-  - Preserve all existing metric presence checks
-
-**Key modified files**:
-
-- `docker/telemetry/integration-test.sh`
-
----
-
-## Task 7.8: Update Documentation
-
-**Objective**: Update all plan docs, runbook, and reference docs to reflect the migration.
-
-**What to do**:
-
-- Edit `docs/telemetry-runbook.md`:
-  - Update `[insight]` config examples to show `server=otel`
-  - Update troubleshooting section (no more StatsD UDP debugging)
-
-- Edit `OpenTelemetryPlan/09-data-collection-reference.md`:
-  - Update Data Flow Overview diagram (remove StatsD receiver)
-  - Update Section 2 header from "StatsD Metrics" to "System Metrics (OTel native)"
-  - Update config examples
-
-- Edit `OpenTelemetryPlan/05-configuration-reference.md`:
-  - Add `server=otel` option to `[insight]` section docs
-
-- Edit `docker/telemetry/TESTING.md`:
-  - Update setup instructions to use `server=otel`
-
-**Key modified files**:
-
-- `docs/telemetry-runbook.md`
-- `OpenTelemetryPlan/09-data-collection-reference.md`
-- `OpenTelemetryPlan/05-configuration-reference.md`
-- `docker/telemetry/TESTING.md`
-
----
-
-## Task 7.9: ValidationTracker — Validation Agreement Computation
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity) — the most valuable metric from the community [xrpl-validator-dashboard](https://github.com/realgrapedrop/xrpl-validator-dashboard).
->
-> **Upstream**: Phase 4 Task 4.8 (validation span attributes provide ledger hash context).
-> **Downstream**: Phase 9 (Validator Health dashboard), Phase 10 (validation checks), Phase 11 (agreement alert rules).
-
-**Objective**: Implement a stateful class that tracks whether our validator's validations agree with network consensus, maintaining rolling 1h and 24h windows with an 8-second grace period and 5-minute late repair window.
-
-**Architecture**:
-
-```
-consensus.validation.send ────> ValidationTracker ────> MetricsRegistry
-(records our validation         (reconciles after       (exports agreement
- for ledger X)                   8s grace period)        gauges every 10s)
-
-ledger.validate ──────────────> ValidationTracker
-(records which ledger           (marks ledger X as
- network validated)              agreed or missed)
-```
-
-**What to do**:
-
-- Create `src/xrpld/telemetry/ValidationTracker.h`:
-  - `recordOurValidation(ledgerHash, ledgerSeq)` — called when we send a validation
-  - `recordNetworkValidation(ledgerHash, seq)` — called when a ledger is fully validated
-  - `reconcile()` — called periodically; reconciles pending ledger events after 8s grace period
-  - Getters: `agreementPct1h()`, `agreementPct24h()`, `agreements1h()`, `missed1h()`, `agreements24h()`, `missed24h()`, `totalAgreements()`, `totalMissed()`, `totalValidationsSent()`, `totalValidationsChecked()`
-  - Thread-safety: atomics for counters, mutex for window deques
-
-- Create `src/xrpld/telemetry/detail/ValidationTracker.cpp`:
-  - Reconciliation logic: after 8s grace period, check if `weValidated && networkValidated && sameHash` → agreement; else missed
-  - Late repair: if a late validation arrives within 5 minutes, correct a false-positive miss
-  - Sliding window: `std::deque<WindowEvent>` evicts entries older than 1h/24h on each reconciliation pass
-  - Ring buffer of 1000 `LedgerEvent` structs for pending reconciliation
-
-- Add recording hooks (modifying Phase 4 code from Phase 7 branch):
-  - `RCLConsensus.cpp` `validate()`: call `tracker.recordOurValidation()`
-  - `LedgerMaster.cpp` fully-validated path: call `tracker.recordNetworkValidation()`
-
-**Key data structures**:
-
-```cpp
-struct LedgerEvent {
-    uint256 ledgerHash;
-    LedgerIndex seq;
-    TimePoint closeTime;
-    bool weValidated = false;
-    bool networkValidated = false;
-    bool reconciled = false;
-    bool agreed = false;
-};
-
-struct WindowEvent {
-    TimePoint time;
-    bool agreed;
-};
-```
-
-**Key new files**:
-
-- `src/xrpld/telemetry/ValidationTracker.h`
-- `src/xrpld/telemetry/detail/ValidationTracker.cpp`
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.h` (add ValidationTracker member)
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (add gauge callback reading from tracker)
-- `src/xrpld/app/consensus/RCLConsensus.cpp` (add recording hooks)
-- `src/xrpld/app/ledger/detail/LedgerMaster.cpp` (add recording hook)
-
-**Exit Criteria**:
-
-- [ ] ValidationTracker correctly tracks agreement with 8s grace period
-- [ ] 5-minute late repair corrects false-positive misses
-- [ ] Thread-safe (atomics + mutex for window deques)
-- [ ] Rolling windows correctly evict stale entries
-- [ ] Unit tests: normal agreement, missed validation, late repair, window eviction
-
----
-
-## Task 7.10: Validator Health Observable Gauges
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Export amendment blocked, UNL health, and quorum data as a native OTel observable gauge.
-
-**What to do**:
-
-- In `MetricsRegistry.cpp` `registerAsyncGauges()`, add:
-
-```cpp
-validatorHealthGauge_ = meter_->CreateDoubleObservableGauge(
-    "xrpld_validator_health", "Validator health indicators");
-```
-
-**Gauge label values**:
-
-| Label `metric=`     | Type   | Source                                            |
-| ------------------- | ------ | ------------------------------------------------- |
-| `amendment_blocked` | int64  | `app_.getOPs().isAmendmentBlocked()` → 0/1        |
-| `unl_blocked`       | int64  | `app_.getOPs().isUNLBlocked()` → 0/1              |
-| `unl_expiry_days`   | double | `app_.validators().expires()` → days until expiry |
-| `validation_quorum` | int64  | `app_.validators().quorum()`                      |
-
-### Sub-task 7.10a: Per-Validator Validation Count (Flag Ledger Window)
-
-**Objective**: Track how many ledgers each UNL validator has validated over
-the last 256 consecutive ledgers (one flag ledger window). This is the key
-UNL participation metric — validators consistently below threshold may be
-candidates for removal from the UNL.
-
-**What to do**:
-
-- Add a new observable gauge:
-
-```cpp
-validatorParticipationGauge_ = meter_->CreateInt64ObservableGauge(
-    "xrpld_validator_participation",
-    "Per-validator validation count over the last 256 ledgers");
-```
-
-- The callback queries `app_.getValidations()` to get the trusted
-  validation set for each of the last 256 ledger hashes (from
-  `LedgerMaster::getValidatedLedger()` walking backwards). For each
-  validator public key in the UNL, count how many of those 256 ledgers
-  have a matching validation.
-
-- **Label dimensions**:
-  - `validator` — base58-encoded validator master public key
-  - `service_instance_id` — this node's identity (standard)
-
-- **Emission**: every flag ledger (256 ledgers, ~15 minutes) or on a
-  10-second async gauge callback with cached results (recompute only
-  at flag ledger boundaries).
-
-- **Data source**: `RCLValidations::getTrustedForLedger(hash, seq)` returns
-  `std::vector<std::shared_ptr<STValidation>>` with `getSignerPublic()`
-  for each. The UNL list is from `app_.getValidators().getTrustedMasterKeys()`.
-
-- **Dashboard panel**: Add a table panel to the Validator Health dashboard
-  showing `xrpld_validator_participation` grouped by `validator` label,
-  with a threshold color (green >= 240, yellow >= 200, red < 200).
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.h/.cpp`
-
-**Exit Criteria**:
-
-- [ ] Gauge emits one time series per UNL validator
-- [ ] Values range 0-256 and update at flag ledger boundaries
-- [ ] Grafana table panel shows per-validator participation
-- [ ] Validators below 75% participation are highlighted in red
-
----
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.h/.cpp`
-
-**Exit Criteria**:
-
-- [ ] All 4 base label values emitted every 10s
-- [ ] `unl_expiry_days` is negative when expired, positive when active
-- [ ] Per-validator participation gauge emits at flag ledger boundaries
-- [ ] Values visible in Prometheus
-
----
-
-## Task 7.11: Peer Quality Observable Gauges
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Export peer health aggregates (latency P90, insane peers, version awareness) as a native OTel observable gauge.
-
-**What to do**:
-
-- In `MetricsRegistry.cpp` `registerAsyncGauges()`, add a callback that iterates `app_.overlay().foreach(...)` to:
-  - Collect per-peer latency values, sort, compute P90
-  - Count peers with `tracking_ == diverged` (insane)
-  - Compare peer `getVersion()` to own version for upgrade awareness
-
-**Gauge label values**:
-
-| Label `metric=`            | Type   | Source                                |
-| -------------------------- | ------ | ------------------------------------- |
-| `peer_latency_p90_ms`      | double | P90 from sorted peer latencies        |
-| `peers_insane_count`       | int64  | Peers with diverged tracking status   |
-| `peers_higher_version_pct` | double | % of peers on newer xrpld version     |
-| `upgrade_recommended`      | int64  | 1 if `peers_higher_version_pct > 60%` |
-
-**Implementation note**: The callback runs every 10s on the metrics reader thread. Iterating ~50-200 peers is acceptable overhead.
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.h/.cpp`
-
-**Exit Criteria**:
-
-- [ ] P90 latency computed correctly
-- [ ] Insane count matches `peers` RPC output
-- [ ] Version comparison handles format variations (e.g., "xrpld-2.4.0-rc1")
-
----
-
-## Task 7.12: Ledger Economy Observable Gauges
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Export fee, reserve, ledger age, and transaction rate as a native OTel observable gauge.
-
-**Gauge label values**:
-
-| Label `metric=`      | Type   | Source                                              |
-| -------------------- | ------ | --------------------------------------------------- |
-| `base_fee_xrp`       | double | Base fee from validated ledger fee settings (drops) |
-| `reserve_base_xrp`   | double | Account reserve from validated ledger (drops)       |
-| `reserve_inc_xrp`    | double | Owner reserve increment (drops)                     |
-| `ledger_age_seconds` | double | `now - lastValidatedCloseTime`                      |
-| `transaction_rate`   | double | Derived: tx count delta / time delta (smoothed)     |
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.h/.cpp`
-
-**Exit Criteria**:
-
-- [ ] Fee values match `server_info` RPC output
-- [ ] `ledger_age_seconds` increases monotonically between ledger closes
-- [ ] `transaction_rate` is smoothed (rolling average)
-
----
-
-## Task 7.13: State Tracking Observable Gauges
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Export extended state value (0-6 encoding combining OperatingMode + ConsensusMode) and time-in-current-state.
-
-**Gauge label values**:
-
-| Label `metric=`                 | Type   | Source                                          |
-| ------------------------------- | ------ | ----------------------------------------------- |
-| `state_value`                   | int64  | 0-6 encoding (see spec for mapping)             |
-| `time_in_current_state_seconds` | double | `now - lastModeChangeTime` from StateAccounting |
-
-**State value encoding**: 0=disconnected, 1=connected, 2=syncing, 3=tracking, 4=full, 5=validating (full + validating), 6=proposing (full + proposing).
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.h/.cpp`
-
-**Exit Criteria**:
-
-- [ ] `state_value` correctly combines OperatingMode and ConsensusMode
-- [ ] `time_in_current_state_seconds` resets on mode change
-
----
-
-## Task 7.14: Storage Detail and Sync Info Gauges
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Export the NodeStore stored-bytes total and initial sync duration.
-
-**Gauge label values**:
-
-| Gauge Name             | Label `metric=`                 | Type   | Source                                               |
-| ---------------------- | ------------------------------- | ------ | ---------------------------------------------------- |
-| `xrpld_storage_detail` | `stored_object_bytes`           | int64  | `Database::getStoreSize()` — cumulative object bytes |
-| `xrpld_sync_info`      | `initial_sync_duration_seconds` | double | Time from start to first FULL                        |
-
-`stored_object_bytes` is not a file size. `getStoreSize()` sums the object payloads
-this process has written, so it excludes NuDB's keys, bucket padding and log, and it
-resets when the process restarts while the files on disk do not. It is the same
-accessor `node_written_bytes` uses, so the two series are equal by construction and
-any write-amplification ratio built from the pair is a constant 1.0. Neither
-`Backend` nor `Database` exposes a file-size accessor, so no metric reports the
-store's on-disk size today.
-
-This label value was `nudb_bytes` when Phase 7 shipped it and was renamed in Phase 9,
-because the value comes from `Database` rather than the NuDB backend.
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.h/.cpp`
-
-**Exit Criteria**:
-
-- [ ] Cumulative stored object bytes reported (0 if NuDB not configured)
-- [ ] Sync duration captured once and remains stable after reaching FULL
-
----
-
-## Task 7.15: New Synchronous Counters
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Add 7 new event counters incremented at their respective instrumentation sites.
-
-| Counter Name                        | Increment Site                   | Source File           |
-| ----------------------------------- | -------------------------------- | --------------------- |
-| `xrpld_ledgers_closed_total`        | `onAccept()` in consensus        | RCLConsensus.cpp      |
-| `xrpld_validations_sent_total`      | `validate()` in consensus        | RCLConsensus.cpp      |
-| `xrpld_validations_checked_total`   | Network validation received      | LedgerMaster.cpp      |
-| `xrpld_validation_agreements_total` | ValidationTracker reconciliation | ValidationTracker.cpp |
-| `xrpld_validation_missed_total`     | ValidationTracker reconciliation | ValidationTracker.cpp |
-| `xrpld_state_changes_total`         | `setMode()` in NetworkOPs        | NetworkOPs.cpp        |
-| `xrpld_jq_trans_overflow_total`     | Job queue overflow path          | JobQueue.cpp          |
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.h/.cpp` (declarations), plus recording sites in RCLConsensus.cpp, LedgerMaster.cpp, NetworkOPs.cpp, JobQueue.cpp
-
-**Exit Criteria**:
-
-- [ ] All 7 counters monotonically increase during normal operation
-- [ ] Counter values match expected rates (e.g., ledgers_closed ≈ 1 per 3-5s)
-
----
-
-## Task 7.16: Validation Agreement Observable Gauge
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Export rolling window agreement stats from `ValidationTracker` (Task 7.9).
-
-**Gauge label values**:
-
-| Gauge Name                   | Label `metric=`     | Type   | Source                      |
-| ---------------------------- | ------------------- | ------ | --------------------------- |
-| `xrpld_validation_agreement` | `agreement_pct_1h`  | double | `tracker.agreementPct1h()`  |
-|                              | `agreements_1h`     | int64  | `tracker.agreements1h()`    |
-|                              | `missed_1h`         | int64  | `tracker.missed1h()`        |
-|                              | `agreement_pct_24h` | double | `tracker.agreementPct24h()` |
-|                              | `agreements_24h`    | int64  | `tracker.agreements24h()`   |
-|                              | `missed_24h`        | int64  | `tracker.missed24h()`       |
-
-**Key modified files**: `src/xrpld/telemetry/MetricsRegistry.cpp`
-
-**Exit Criteria**:
-
-- [ ] Agreement percentages in range [0.0, 100.0]
-- [ ] Window stats stabilize after 1h/24h of operation
-
----
-
-## Summary Table
-
-| Task | Description                            | New Files | Modified Files | Depends On |
-| ---- | -------------------------------------- | --------- | -------------- | ---------- |
-| 7.1  | Add OTel Metrics SDK to build deps     | 0         | 2              | —          |
-| 7.2  | Implement OTelCollector class          | 2         | 0              | 7.1        |
-| 7.3  | Update CollectorManager config routing | 0         | 2              | 7.2        |
-| 7.4  | Update OTel Collector YAML and Docker  | 0         | 2              | 7.3        |
-| 7.5  | Preserve metric names in Prometheus    | 0         | 1              | 7.2        |
-| 7.6  | Update Grafana dashboards (if needed)  | 0         | 3              | 7.5        |
-| 7.7  | Update integration tests               | 0         | 1              | 7.4        |
-| 7.8  | Update documentation                   | 0         | 4              | 7.6        |
-| 7.9  | ValidationTracker (agreement tracking) | 2         | 4              | 7.2, P4.8  |
-| 7.10 | Validator health observable gauges     | 0         | 2              | 7.2        |
-| 7.11 | Peer quality observable gauges         | 0         | 2              | 7.2        |
-| 7.12 | Ledger economy observable gauges       | 0         | 2              | 7.2        |
-| 7.13 | State tracking observable gauges       | 0         | 2              | 7.2        |
-| 7.14 | Storage detail and sync info gauges    | 0         | 2              | 7.2        |
-| 7.15 | New synchronous counters               | 0         | 6              | 7.2        |
-| 7.16 | Validation agreement observable gauge  | 0         | 1              | 7.9        |
-
-**Parallel work**: Tasks 7.4 and 7.5 can run in parallel after 7.2/7.3 complete. Task 7.6 depends on 7.5's findings. Tasks 7.7 and 7.8 can run in parallel after 7.6. Tasks 7.10-7.14 can all run in parallel after 7.2. Task 7.15 depends on 7.2. Task 7.16 depends on 7.9. Task 7.9 depends on 7.2 and Phase 4 Task 4.8.
-
-**Exit Criteria** (from [06-implementation-phases.md §6.8](./06-implementation-phases.md)):
-
-- [ ] All 255+ metrics visible in Prometheus via OTLP pipeline (no StatsD receiver)
-- [ ] `server=otel` is the default in development docker-compose
-- [ ] `server=statsd` still works as a fallback
-- [ ] Existing Grafana dashboards display data correctly
-- [ ] Integration test passes with OTLP-only metrics pipeline
-- [ ] No performance regression vs StatsD baseline (< 1% CPU overhead)
-- [ ] Deferred Task 6.1 (`|m` wire format) no longer relevant — Meter mapped to OTel Counter
-- [ ] ValidationTracker agreement % stabilizes after 1h under normal consensus
-- [ ] All new gauges and counters visible in Prometheus with non-zero values

OpenTelemetryPlan/Phase8_taskList.md

@@ -1,239 +0,0 @@
-# Phase 8: Log-Trace Correlation and Centralized Log Ingestion — Task List
-
-> **Goal**: Inject trace context (trace_id, span_id) into xrpld's Journal log output for log-trace correlation, and add OTel Collector filelog receiver to ingest logs into Grafana Loki for unified observability.
->
-> **Scope**: Two independent sub-phases — 8a (code change: trace_id in logs) and 8b (infra only: filelog receiver to Loki). No changes to the `beast::Journal` public API.
->
-> **Branch**: `pratik/otel-phase8-log-correlation` (from `pratik/otel-phase7-native-metrics`)
-
-### Related Plan Documents
-
-| Document                                                         | Relevance                                                      |
-| ---------------------------------------------------------------- | -------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)     | Phase 8 plan: motivation, architecture, exit criteria (§6.8.1) |
-| [07-observability-backends.md](./07-observability-backends.md)   | Loki backend recommendation, Grafana data source provisioning  |
-| [Phase7_taskList.md](./Phase7_taskList.md)                       | Prerequisite — native OTel metrics pipeline must be working    |
-| [05-configuration-reference.md](./05-configuration-reference.md) | `[telemetry]` config (trace_id injection toggle)               |
-
----
-
-## Task 8.1: Inject trace_id into Logs::format()
-
-**Objective**: Add OTel trace context to every log line that is emitted within an active, sampled span. The sampled flag matters because a span dropped by the `ParentBasedSampler` still carries its parent's ids, so emitting them would advertise a trace that was never exported.
-
-**What to do**:
-
-- Edit `src/libxrpl/basics/Log.cpp`:
-  - In `Logs::format()` (around line 346), after severity is appended, check for active OTel span. The implementation checks the context value directly to avoid the heap allocation that `GetSpan()` performs on the no-span path:
-    ```cpp
-    #ifdef XRPL_ENABLE_TELEMETRY
-    {
-        auto context = opentelemetry::context::RuntimeContext::GetCurrent();
-        auto spanValue = context.GetValue(opentelemetry::trace::kSpanKey);
-        if (opentelemetry::nostd::holds_alternative<
-                opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span>>(spanValue))
-        {
-            auto span = opentelemetry::nostd::get<
-                opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span>>(spanValue);
-            auto spanCtx = span->GetContext();
-            if (spanCtx.IsValid() && spanCtx.IsSampled())
-            {
-                char traceId[32], spanId[16];
-                spanCtx.trace_id().ToLowerBase16(
-                    opentelemetry::nostd::span<char, 32>{traceId});
-                spanCtx.span_id().ToLowerBase16(
-                    opentelemetry::nostd::span<char, 16>{spanId});
-                output += "trace_id=";
-                output.append(traceId, 32);
-                output += " span_id=";
-                output.append(spanId, 16);
-                output += ' ';
-            }
-        }
-    }
-    #endif
-    ```
-  - Add `#include` for OTel context headers, guarded by `#ifdef XRPL_ENABLE_TELEMETRY`
-
-- Edit `include/xrpl/basics/Log.h`:
-  - No changes needed — format() signature unchanged
-
-**Key modified files**:
-
-- `src/libxrpl/basics/Log.cpp`
-
-**Performance note**: The implementation checks the thread-local context value directly (avoiding the heap allocation that `GetSpan()` performs on the no-span path). On threads without an active span (~99% of log lines), the cost is a thread-local read + variant type check (~15-20ns). On the active-span path, an additional shared_ptr copy + `GetContext()` + `IsValid()`/`IsSampled()` adds ~50ns total. Overhead is negligible at typical logging rates.
-
----
-
-## Task 8.2: Add Loki to Docker Compose Stack
-
-**Objective**: Add Grafana Loki as a log storage backend in the development observability stack.
-
-**What to do**:
-
-- Edit `docker/telemetry/docker-compose.yml`:
-  - Add Loki service:
-    ```yaml
-    loki:
-      image: grafana/loki:3.7.6
-      ports:
-        - "3100:3100"
-      command: -config.file=/etc/loki/local-config.yaml
-    ```
-  - Add Loki as a Grafana data source in provisioning
-
-- Create `docker/telemetry/grafana/provisioning/datasources/loki.yaml`:
-  - Configure Loki data source with derived fields linking `trace_id` to Tempo
-
-**Key new files**:
-
-- `docker/telemetry/grafana/provisioning/datasources/loki.yaml`
-
-**Key modified files**:
-
-- `docker/telemetry/docker-compose.yml`
-
----
-
-## Task 8.3: Add Filelog Receiver to OTel Collector
-
-**Objective**: Configure the OTel Collector to tail xrpld's log file and export to Loki.
-
-**What to do**:
-
-- Edit `docker/telemetry/otel-collector-config.yaml`:
-  - Add `filelog` receiver:
-    ```yaml
-    receivers:
-      filelog:
-        include: [/var/log/xrpld/*/debug.log]
-        operators:
-          - type: regex_parser
-            regex: '^(?P<timestamp>\S+)\s+(?P<partition>\S+):(?P<severity>\S+)\s+(?:trace_id=(?P<trace_id>[a-f0-9]+)\s+span_id=(?P<span_id>[a-f0-9]+)\s+)?(?P<message>.*)$'
-            timestamp:
-              parse_from: attributes.timestamp
-              layout: "%Y-%m-%dT%H:%M:%S.%fZ"
-    ```
-  - Add logs pipeline:
-    ```yaml
-    service:
-      pipelines:
-        logs:
-          receivers: [filelog]
-          processors: [batch]
-          exporters: [otlp/loki]
-    ```
-  - Add Loki exporter:
-    ```yaml
-    exporters:
-      otlphttp/loki:
-        endpoint: http://loki:3100/otlp
-    ```
-
-- Mount xrpld's log directory into the collector container via docker-compose volume
-
-**Key modified files**:
-
-- `docker/telemetry/otel-collector-config.yaml`
-- `docker/telemetry/docker-compose.yml`
-
----
-
-## Task 8.4: Configure Grafana Trace-to-Log Correlation
-
-**Objective**: Enable one-click navigation from Tempo traces to Loki logs in Grafana.
-
-**What to do**:
-
-- Edit Grafana Tempo data source provisioning to add `tracesToLogs` configuration:
-
-  ```yaml
-  tracesToLogs:
-    datasourceUid: loki
-    filterByTraceID: true
-    filterBySpanID: false
-    tags: ["partition", "severity"]
-  ```
-
-- Edit Grafana Loki data source provisioning to add `derivedFields` linking trace_id back to Tempo:
-  ```yaml
-  derivedFields:
-    - datasourceUid: tempo
-      matcherRegex: "trace_id=(\\w+)"
-      name: TraceID
-      url: "$${__value.raw}"
-  ```
-
-**Key modified files**:
-
-- `docker/telemetry/grafana/provisioning/datasources/loki.yaml`
-- `docker/telemetry/grafana/provisioning/datasources/` (Tempo data source file)
-
----
-
-## Task 8.5: Update Integration Tests
-
-**Objective**: Verify trace_id appears in logs and Loki correlation works.
-
-**What to do**:
-
-- Edit `docker/telemetry/integration-test.sh`:
-  - After sending RPC requests (which create spans), grep xrpld's log output for `trace_id=`
-  - Verify trace_id matches a trace visible in Tempo
-  - Optionally: query Loki via API to confirm log ingestion
-
-**Key modified files**:
-
-- `docker/telemetry/integration-test.sh`
-
----
-
-## Task 8.6: Update Documentation
-
-**Objective**: Document the log correlation feature in runbook and reference docs.
-
-**What to do**:
-
-- Edit `docs/telemetry-runbook.md`:
-  - Add "Log-Trace Correlation" section explaining how to use Grafana Tempo -> Loki linking
-  - Add LogQL query examples for filtering by trace_id
-
-- Edit `OpenTelemetryPlan/09-data-collection-reference.md`:
-  - Add new section "3. Log Correlation" between SpanMetrics and StatsD sections
-  - Document the log format with trace_id injection
-  - Document Loki as a new backend
-
-- Edit `docker/telemetry/TESTING.md`:
-  - Add log correlation verification steps
-
-**Key modified files**:
-
-- `docs/telemetry-runbook.md`
-- `OpenTelemetryPlan/09-data-collection-reference.md`
-- `docker/telemetry/TESTING.md`
-
----
-
-## Summary Table
-
-| Task | Description                                | Sub-Phase | New Files | Modified Files | Depends On |
-| ---- | ------------------------------------------ | --------- | --------- | -------------- | ---------- |
-| 8.1  | Inject trace_id into Logs::format()        | 8a        | 0         | 1              | Phase 7    |
-| 8.2  | Add Loki to Docker Compose stack           | 8b        | 1         | 1              | --         |
-| 8.3  | Add filelog receiver to OTel Collector     | 8b        | 0         | 2              | 8.1, 8.2   |
-| 8.4  | Configure Grafana trace-to-log correlation | 8b        | 0         | 2              | 8.3        |
-| 8.5  | Update integration tests                   | 8a + 8b   | 0         | 1              | 8.4        |
-| 8.6  | Update documentation                       | 8a + 8b   | 0         | 3              | 8.5        |
-
-**Parallel work**: Task 8.2 (Loki infra) can run in parallel with Task 8.1 (code change). Tasks 8.3-8.6 are sequential.
-
-**Exit Criteria** (from [06-implementation-phases.md §6.8.1](./06-implementation-phases.md)):
-
-- [ ] Log lines within active, sampled spans contain `trace_id=<hex> span_id=<hex>`
-- [ ] Log lines outside spans have no trace context (no empty fields)
-- [ ] Loki ingests xrpld logs via OTel Collector filelog receiver
-- [ ] Grafana Tempo -> Loki one-click correlation works
-- [ ] Grafana Loki -> Tempo reverse lookup works via derived field
-- [ ] Integration test verifies trace_id presence in logs
-- [ ] No performance regression from trace_id injection (< 0.1% overhead)

OpenTelemetryPlan/Phase9_taskList.md

@@ -1,928 +0,0 @@
-<!-- cspell:ignore ISTOGRAM -->
-<!-- The all-caps macro name XRPL_METRIC_HISTOGRAM_RECORD trips cspell's
-     compound-word splitter, which emits the subword "ISTOGRAM"; ignore it here. -->
-
-# Phase 9: Internal Metric Instrumentation Gap Fill — Task List
-
-> **Status**: Complete for Tasks 9.1-9.13. Tasks 9.14-9.17 remain open by design
-> (see each task for the blocker).
->
-> **Goal**: Instrument xrpld to emit ~50+ metrics that exist in `get_counts`/`server_info`/TxQ/PerfLog but currently lack time-series export via the OTel or beast::insight pipelines.
->
-> **Scope**: Hybrid approach — extend `beast::insight` for metrics near existing registrations, use OTel Metrics SDK `ObservableGauge` callbacks for new categories (TxQ, PerfLog, CountedObjects).
->
-> **Branch**: `pratik/otel-phase9-metric-gap-fill` (from `pratik/otel-phase8-log-correlation`)
->
-> **Depends on**: Phase 7 (native OTel metrics pipeline) and Phase 8 (log-trace correlation)
-
-> **Note on metric names**: there is **no `xrpld_` prefix** on any emitted
-> metric. `77f35c03db` removed it and lowercased names, and
-> `OTelCollectorImp::formatName()`
-> (`src/libxrpl/beast/insight/OTelCollector.cpp:855-874`) adds no prefix at all —
-> it only lowercases the raw name and turns `.` and spaces into `_`. Earlier
-> revisions of this task list spelled every metric `xrpld_<name>`; those spellings
-> have been corrected in place to the emitted names, so the names below can be
-> pasted into Prometheus as written. Instruments created in
-> `src/xrpld/telemetry/MetricsRegistry.cpp` (35 of them) are the single source of
-> truth. `MetricsRegistry.h`'s Doxygen used to disagree on three histogram names;
-> those header comments were repaired in this change set (see Tasks 9.4 and 9.5),
-> so header and `.cpp` now agree.
->
-> **Two shapes do not simply lose the prefix**, so `xrpld_<name>` → `<name>` is
-> not a blanket rule:
->
-> - **Multiplexed observable gauges.** Most of the value names in these task
->   descriptions are a **`metric` label value** on a shared instrument, not a
->   standalone metric name — queue depth is `txq_metrics{metric="txq_count"}`, not
->   `txq_count`. The same applies to `nodestore_state`, `cache_metrics`,
->   `load_factor_metrics`, `server_info`, `db_metrics`, `validator_health`,
->   `peer_quality`, `state_tracking` and `ledger_economy`. Each task below names
->   its owning instrument.
-> - **Unit-suffixed histograms** coming through `beast::insight`.
->   `OTelCollectorImp` appends the unit to the name, so the `ios_latency`
->   histogram is `ios_latency_milliseconds_bucket` in Prometheus — not
->   `ios_latency_bucket`. Instruments created directly on `MetricsRegistry` keep
->   their literal name (`job_queued_us_bucket`, `rpc_method_us_bucket`) because
->   the unit is already in the instrument name.
-
-### Related Plan Documents
-
-| Document                                                             | Relevance                                                      |
-| -------------------------------------------------------------------- | -------------------------------------------------------------- |
-| [06-implementation-phases.md](./06-implementation-phases.md)         | Phase 9 plan: motivation, architecture, exit criteria (§6.8.2) |
-| [09-data-collection-reference.md](./09-data-collection-reference.md) | Current metric inventory + future metrics section              |
-| [Phase7_taskList.md](./Phase7_taskList.md)                           | Prerequisite — OTel Metrics SDK and `OTelCollector` class      |
-| [Phase8_taskList.md](./Phase8_taskList.md)                           | Prerequisite — log-trace correlation                           |
-
-### Third-Party Consumer Context
-
-These metrics serve multiple external consumer categories identified during research:
-
-| Consumer Category         | Key Metrics They Need                                           |
-| ------------------------- | --------------------------------------------------------------- |
-| **Exchanges**             | Fee escalation levels, TxQ depth, settlement latency            |
-| **Payment Processors**    | Load factors, io_latency, transaction throughput                |
-| **Analytics Providers**   | NodeStore I/O, cache hit rates, counted objects                 |
-| **Validators/Operators**  | Per-job execution times, PerfLog RPC counters, consensus timing |
-| **Academic Researchers**  | Consensus performance time-series, fee market dynamics          |
-| **Institutional Custody** | Server health scores, reserve calculations, node availability   |
-
----
-
-## Task 9.1: NodeStore I/O Metrics
-
-**Objective**: Export node store read/write performance as time-series metrics.
-
-**What to do**:
-
-> **As shipped, this did _not_ go through `beast::insight`.** `Database.cpp` has
-> no insight members. The metrics are a single `nodestore_state`
-> `Int64ObservableGauge` on `MetricsRegistry`
-> (`src/xrpld/telemetry/MetricsRegistry.cpp:957-965`) whose callback reads
-> `Database`'s public accessors (`getFetchTotalCount()`, `getFetchHitCount()`,
-> `getStoreCount()`, `getFetchDurationUs()`, `getStoreDurationUs()`, …) and
-> multiplexes every value onto the `metric` label. Write-queue depth comes from
-> the new `include/xrpl/nodestore/WriteStats.h`.
-
-- Export the following as `nodestore_state{metric="…"}` label values:
-  - Gauge: `node_reads_total` (cumulative read operations)
-  - Gauge: `node_reads_hit` (fetches that found an object — not a cache hit; `fetchHitCount_` increments whatever served the fetch)
-  - Gauge: `node_writes` (cumulative write operations)
-  - Gauge: `node_written_bytes` (cumulative bytes written)
-  - Gauge: `node_read_bytes` (cumulative bytes read)
-  - Gauge: `node_reads_duration_us` (cumulative read time in microseconds)
-  - Gauge: `write_load` (current write load score)
-  - Gauge: `read_queue` (items in read queue)
-
-- These values are already computed in `Database::getCountsJson()`. The gauge
-  callback reads the same counters through `Database`'s public accessors.
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (the `nodestore_state` gauge)
-- `include/xrpl/nodestore/Database.h` (accessors; **not** `src/libxrpl/nodestore/Database.h`, which does not exist)
-- `include/xrpl/nodestore/WriteStats.h` (new — write-queue depth snapshot)
-
-**Derived Prometheus metrics**: `nodestore_state{metric="node_reads_total"}`,
-`nodestore_state{metric="node_reads_hit"}`, `nodestore_state{metric="write_load"}`,
-etc. There is **no** `xrpld_` prefix — `OTelCollectorImp::formatName()` adds none.
-
-**Grafana dashboard**: Add "NodeStore I/O" panel group to _Node Health_ dashboard.
-
----
-
-## Task 9.2: Cache Hit Rate Metrics
-
-**Objective**: Export SHAMap and ledger cache performance as time-series gauges.
-
-**What to do**:
-
-- Register OTel `ObservableGauge` callbacks (via Phase 7's `OTelCollector`) for:
-  - `SLE_hit_rate` — SLE cache hit rate (0.0–1.0)
-  - `ledger_hit_rate` — Ledger object cache hit rate
-  - `AL_hit_rate` — AcceptedLedger cache hit rate
-  - `treenode_cache_size` — SHAMap TreeNode cache size (entries)
-  - `treenode_track_size` — Tracked tree nodes
-  - `fullbelow_size` — FullBelow cache size
-
-- The callback reads from the same sources as the `GetCounts` handler
-  (`src/xrpld/rpc/handlers/admin/status/GetCounts.cpp` — **not**
-  `src/xrpld/rpc/handlers/GetCounts.cpp`).
-
-- Create a centralized `MetricsRegistry` class that holds all OTel async gauge registrations, polled at 10-second intervals by the `PeriodicMetricReader`.
-
-**Key modified files**:
-
-- New: `src/xrpld/telemetry/MetricsRegistry.h` / `.cpp`
-- New: `src/xrpld/telemetry/MetricMacros.h` (the `XRPL_METRIC_*` call-site macros)
-- `src/xrpld/rpc/handlers/admin/status/GetCounts.cpp` (extract shared access methods)
-- `src/xrpld/app/main/Application.cpp` (register MetricsRegistry at startup)
-
-**Derived Prometheus metrics**: `cache_metrics{metric="SLE_hit_rate"}`,
-`cache_metrics{metric="ledger_hit_rate"}`, `cache_metrics{metric="treenode_cache_size"}`,
-etc. Label values are **case-sensitive** (`SLE_hit_rate`, `AL_size`, `AL_hit_rate`).
-
----
-
-## Task 9.3: Transaction Queue (TxQ) Metrics
-
-**Objective**: Export TxQ depth, capacity, and fee escalation levels as time-series.
-
-**What to do**:
-
-- Register OTel `ObservableGauge` callbacks for TxQ state (from
-  `src/xrpld/app/misc/TxQ.h` — **not** `src/xrpld/app/tx/detail/TxQ.h`):
-  - `txq_count` — Current transactions in queue
-  - `txq_max_size` — Maximum queue capacity
-  - `txq_in_ledger` — Transactions in current open ledger
-  - `txq_per_ledger` — Expected transactions per ledger
-  - `txq_reference_fee_level` — Reference fee level
-  - `txq_min_processing_fee_level` — Minimum fee to get processed
-  - `txq_med_fee_level` — Median fee level in queue
-  - `txq_open_ledger_fee_level` — Open ledger fee escalation level
-
-- Add to the `MetricsRegistry` (Task 9.2).
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (add TxQ callbacks)
-- `src/xrpld/app/misc/TxQ.h` (expose metrics accessor if needed)
-
-**Derived Prometheus metrics**: `txq_metrics{metric="txq_count"}`,
-`txq_metrics{metric="txq_max_size"}`, `txq_metrics{metric="txq_open_ledger_fee_level"}`, etc.
-There is one instrument, `txq_metrics` (`MetricsRegistry.cpp:705`); each value above
-is a `metric` label value, not a metric name of its own.
-
-**Grafana dashboard**: New _Fee Market & TxQ_ dashboard (`fee-market`).
-
----
-
-## Task 9.4: PerfLog Per-RPC Method Metrics
-
-**Objective**: Export per-RPC-method call counts and latency as OTel metrics.
-
-**What to do**:
-
-- Register OTel instruments for PerfLog RPC counters (from `PerfLogImp.cpp`):
-  - Counter: `rpc_method_started_total{method="<name>"}` — calls started
-  - Counter: `rpc_method_finished_total{method="<name>"}` — calls completed
-  - Counter: `rpc_method_errored_total{method="<name>"}` — calls errored
-  - Histogram: `rpc_method_us{method="<name>"}` — execution time distribution
-
-- Use OTel `Counter<uint64_t>` and `Histogram<double>` instruments with the
-  `method` attribute label. The RPC instruments carry **only** `method`
-  (`MetricsRegistry.cpp:436-475`) — the `handler` label belongs to the job
-  instruments (Task 9.5), not these.
-
-> **Naming**: the instrument is `rpc_method_us` — declared as
-> `kRpcMethodDurationUs` at `MetricsRegistry.cpp:96` and used both to register the
-> explicit-bucket view and to create the instrument. `MetricsRegistry.h`'s Doxygen
-> comment used to read `rpc_method_duration_us`; **that was fixed in this change**
-> (`MetricsRegistry.h:789`), so header and `.cpp` now agree and there is no
-> caveat left. The prefix `xrpld_` in the original spec is not emitted by anything.
->
-> Same for the job histograms in Task 9.5: `job_queued_us` / `job_running_us`.
-
-- Hook into the existing PerfLog callback mechanism rather than adding new instrumentation points.
-
-**Key modified files**:
-
-- `src/xrpld/perflog/detail/PerfLogImp.cpp` (add OTel instrument updates alongside existing JSON counters)
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (register instruments)
-
-**Derived Prometheus metrics**: `rpc_method_started_total{method="server_info"}`, `rpc_method_us_bucket{method="ledger"}`, etc.
-
-**Grafana dashboard**: Add "Per-Method RPC Breakdown" panel group to _RPC Performance_ dashboard.
-
----
-
-## Task 9.5: PerfLog Per-Job-Type Metrics
-
-**Objective**: Export per-job-type queue and execution metrics.
-
-**What to do**:
-
-- Register OTel instruments for PerfLog job counters. All five carry **two**
-  labels — `job_type` and `handler` — so producers sharing a job type stay
-  distinguishable (`MetricsRegistry.h:794-818`, recorded at
-  `MetricsRegistry.cpp:498,518,527,548,553`). `handler` is the sanitised
-  `addJob` name; `sanitiseHandler()` folds dynamic names into a bounded domain
-  of exactly 44 values, so cardinality stays fixed.
-  - Counter: `job_queued_total{job_type="<name>",handler="<name>"}` — jobs queued
-  - Counter: `job_started_total{job_type="<name>",handler="<name>"}` — jobs started
-  - Counter: `job_finished_total{job_type="<name>",handler="<name>"}` — jobs completed
-  - Histogram: `job_queued_us{job_type="<name>",handler="<name>"}` — time spent waiting in queue
-  - Histogram: `job_running_us{job_type="<name>",handler="<name>"}` — execution time distribution
-
-> **Naming**: the instruments are `job_queued_us` / `job_running_us`
-> (`kJobQueuedDurationUs` / `kJobRunningDurationUs`, `MetricsRegistry.cpp:94-95`).
-> `MetricsRegistry.h`'s Doxygen comments used to read
-> `job_queued_duration_us` / `job_running_duration_us`; **both were fixed in this
-> change** (`MetricsRegistry.h:810,815`), so there is no header/`.cpp` divergence
-> left to work around.
-
-- Hook into PerfLog's existing job tracking alongside Task 9.4.
-
-**Key modified files**:
-
-- `src/xrpld/perflog/detail/PerfLogImp.cpp`
-- `src/xrpld/telemetry/MetricsRegistry.cpp`
-
-**Derived Prometheus metrics**: `job_queued_total{job_type="ledgerData",handler="ProcessLData"}`, `job_running_us_bucket{job_type="transaction",handler="…"}`, etc.
-
-**Grafana dashboard**: New _Job Queue Analysis_ dashboard (`job-queue`).
-
----
-
-## Task 9.6: Counted Object Instance Metrics
-
-**Objective**: Export live instance counts for key internal object types.
-
-**What to do**:
-
-- Register OTel `ObservableGauge` callbacks for `CountedObject<T>` instance counts:
-  - `object_count{type="xrpl::Transaction"}` — live Transaction objects
-  - `object_count{type="xrpl::Ledger"}` — live Ledger objects
-  - `object_count{type="xrpl::NodeObject"}` — live NodeObject instances
-  - `object_count{type="xrpl::STTx"}` — serialized transaction objects
-  - `object_count{type="xrpl::STLedgerEntry"}` — serialized ledger entries
-  - `object_count{type="xrpl::InboundLedger"}` — ledgers being fetched
-  - `object_count{type="xrpl::Pathfinder"}` — active pathfinding computations
-  - `object_count{type="xrpl::PathRequest"}` — active path requests
-  - `object_count{type="xrpl::HashRouter::Entry"}` — hash router entries (the type is
-    `HashRouter::Entry`; there is no `HashRouterEntry` type)
-
-- The `CountedObject` template already tracks these via atomic counters. The callback just reads the current counts.
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (add counted object callbacks)
-- `include/xrpl/basics/CountedObject.h` (may need static accessor for iteration)
-
-**Derived Prometheus metrics**: `object_count{type="xrpl::Transaction"}`, `object_count{type="xrpl::NodeObject"}`, etc.
-The `type` label value is `beast::typeName<Object>()` — the fully-qualified
-demangled C++ type name (`CountedObject.h:109`), not a short word.
-
-**Grafana dashboard**: Add "Object Instance Counts" panel to _Node Health_ dashboard.
-
----
-
-## Task 9.7: Fee Escalation & Load Factor Metrics
-
-**Objective**: Export the full load factor breakdown as time-series.
-
-**What to do**:
-
-- Register OTel `ObservableGauge` callbacks for load factors (from `NetworkOPs.cpp` line ~2694):
-  - `load_factor` — combined transaction cost multiplier
-  - `load_factor_server` — server + cluster + network contribution
-  - `load_factor_local` — local server load only
-  - `load_factor_net` — network-wide load estimate
-  - `load_factor_cluster` — cluster peer load
-  - `load_factor_fee_escalation` — open ledger fee escalation
-  - `load_factor_fee_queue` — queue entry fee level
-
-- These overlap with some existing StatsD metrics but provide finer granularity (individual factor breakdown vs. combined value).
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.cpp`
-- `src/xrpld/app/misc/NetworkOPs.cpp` (expose load factor accessors if needed)
-
-**Derived Prometheus metrics**: `load_factor_metrics{metric="load_factor"}`,
-`load_factor_metrics{metric="load_factor_fee_escalation"}`, etc. There is one
-instrument, `load_factor_metrics` (`MetricsRegistry.cpp:785`); every value listed
-above is a `metric` label value, not a metric name of its own.
-
-**Grafana dashboard**: Add "Load Factor Breakdown" panel to _Fee Market & TxQ_ dashboard.
-
----
-
-## Task 9.7a: push_metrics.py Parity — Missing Observable Gauges
-
-**Objective**: Fill the remaining metric gaps between the external `push_metrics.py` script (in `ripplex-ansible`) and the internal OTel `MetricsRegistry` observable gauges. After this task, all metrics collected by `push_metrics.py` that CAN be collected internally are covered.
-
-**What was done**:
-
-- Extended existing `cacheHitRateGauge_` callback with `AL_size` (AcceptedLedger cache size)
-- Extended existing `nodeStoreGauge_` callback with 4 new metrics from `getCountsJson()`:
-  - `node_reads_duration_us` (JSON string — uses `std::stoll(asString())`)
-  - `read_request_bundle` (native JSON int)
-  - `read_threads_running` (native JSON int)
-  - `read_threads_total` (native JSON int)
-- Added new `server_info` Int64ObservableGauge with 8 metrics:
-  - `server_state` — operating mode as int (0=DISCONNECTED .. 4=FULL)
-  - `uptime` — seconds since server start
-  - `peers` — total peer count
-  - `validated_ledger_seq` — validated ledger sequence (atomic read)
-  - `ledger_current_index` — current open ledger sequence
-  - `peer_disconnects_resources` — cumulative resource-related disconnects
-  - `last_close_proposers` — from `getConsensusInfo()["previous_proposers"]`
-  - `last_close_converge_time_ms` — from `getConsensusInfo()["previous_mseconds"]`
-- Added new `build_info` Int64ObservableGauge (info-style, value=1 with `version` label)
-- Added new `complete_ledgers` Int64ObservableGauge parsing comma-separated ranges into `{bound, index}` pairs
-- Added new `db_metrics` Int64ObservableGauge with 4 metrics:
-  - `db_kb_total`, `db_kb_ledger`, `db_kb_transaction` (SQLite stat queries)
-  - `historical_perminute` (historical ledger fetch rate)
-
-**Key modified files**:
-
-- `src/xrpld/telemetry/MetricsRegistry.h` (4 new gauge members, updated ASCII diagram)
-- `src/xrpld/telemetry/MetricsRegistry.cpp` (4 new callback registrations, 2 callback extensions)
-
-**Not implementable inside xrpld**:
-
-- `connection_count_51233/51234` — OS-level port connection counts from external shell script (`get_connection.sh`)
-
-**Derived Prometheus metrics**: `server_info{metric="server_state"}`, `build_info{version="2.4.0"}`, `complete_ledgers{bound="start",index="0"}`, `db_metrics{metric="db_kb_total"}`, etc.
-
-**Grafana dashboard**: New panels added to _Node Health_ dashboard (`node-health.json`).
-
----
-
-## Task 9.8: New Grafana Dashboards
-
-**Objective**: Create Grafana dashboards for the new metric categories.
-
-**What to do**:
-
-- Create 2 new dashboards:
-  1. **Fee Market & TxQ** (`fee-market`) — TxQ depth/capacity, fee levels, load factor breakdown, fee escalation timeline
-  2. **Job Queue Analysis** (`job-queue`) — Per-job-type rates, queue wait times, execution times, job queue depth
-
-- Update 2 existing dashboards:
-  1. **Node Health** (`node-health`) — Add NodeStore I/O panels, cache hit rate panels, object instance counts
-  2. **RPC Performance** (`rpc-performance`) — Add per-method RPC breakdown panels
-
-> Tasks 9.11-9.13 add two more new dashboards (`validator-health`,
-> `peer-quality`), so Phase 9's total is **4 new + 2 updated**.
-
-**Key modified files** (filenames and uids after the `dashboards/rippled-*` →
-bare rename in `145b1469d6` and `25868f2740` — the
-`dashboards/rippled-*.json` paths no longer exist):
-
-- New: `docker/telemetry/grafana/dashboards/fee-market.json` (uid `fee-market`)
-- New: `docker/telemetry/grafana/dashboards/job-queue.json` (uid `job-queue`)
-- `docker/telemetry/grafana/dashboards/node-health.json` (uid `node-health`)
-- `docker/telemetry/grafana/dashboards/rpc-performance.json` (uid `rpc-performance`)
-
----
-
-## Task 9.9: Update Documentation
-
-**Objective**: Update telemetry reference docs with all new metrics.
-
-**What to do**:
-
-- Update `OpenTelemetryPlan/09-data-collection-reference.md`: ✅ done
-  - Add new section for OTel SDK-exported metrics (NodeStore, cache, TxQ, PerfLog, CountedObjects, load factors) — §5b + "Phase 9: OTel SDK-Exported Metrics (MetricsRegistry)"
-  - Update Grafana dashboard reference table (add 4 new dashboards) — "New Grafana Dashboards (Phase 9)" / "Updated Grafana Dashboards (Phase 9)"
-  - Add Prometheus query examples for new metrics
-
-- Update `docs/telemetry-runbook.md`:
-  - ✅ Alerting section covering the provisioned rules and how to wire a receiver
-  - ✅ Troubleshooting entries for new metric categories
-  - ❌ **Still open**: dashboard guides for **six** dashboards — `fee-market`,
-    `job-queue`, `ledger-data-sync`, `overlay-traffic-detail`, `peer-quality` and
-    `validator-health`. The runbook's dashboard reference records the gap
-    verbatim: "Nine dashboards have a reference section below. `fee-market`,
-    `job-queue`, `ledger-data-sync`, `overlay-traffic-detail`, `peer-quality`, and
-    `validator-health` are provisioned but not yet documented here — their panel
-    descriptions carry the same six-heading reference format, so open the panel
-    info icon in Grafana until a section is written." (15 provisioned − 6
-    undocumented = 9 documented.) Also still open: the Validation Agreement
-    explainer (8s grace / 5m late repair)
-
-- Provision Grafana alert rules (`docker/telemetry/grafana/provisioning/alerting/`) — **as shipped**:
-  - **13 rules in 5 groups**: `xrpld-consensus` (`LedgerHistoryMismatch`,
-    `LedgerCloseStalled`, `ValidatedLedgerStale`), `xrpld-validator`
-    (`ValidationsMissed`, `ValidationsNotChecked`), `xrpld-jobqueue`
-    (`JobQueueTxOverflow`, `JobQueueLatencyHigh`, `NodeStoreIOLatencyHigh`),
-    `xrpld-node-state` (`NodeStateFlapping`, `NodeNotFull`), `xrpld-overlay`
-    (`ManifestJobQueueConvoy`, `ManifestFloodInbound`, `PeerResourceDisconnects`)
-  - **2 contact points** — `xrpld-default` (Slack) and `xrpld-critical`
-    (Slack + email) — and a **nested** notification policy: root →
-    `xrpld-default`, child route `severity = critical` → `xrpld-critical`.
-    Auto-loaded via the existing `provisioning/` mount (no docker-compose change)
-  - 3 rules are `severity: critical`, 10 are `severity: warning`
-  - Alerting operator docs (per-alert meaning, tuning, receiver wiring) now live in the Alerting section of `docs/telemetry-runbook.md`
-
-**Key modified files**:
-
-- `OpenTelemetryPlan/09-data-collection-reference.md`
-- `docs/telemetry-runbook.md`
-- `docker/telemetry/grafana/provisioning/alerting/{rules,contactpoints,policies}.yaml` (new)
-- `docs/telemetry-runbook.md` (Alerting section added)
-
----
-
-## Task 9.10: Integration Tests
-
-**Objective**: Verify all new metrics appear in Prometheus after a test workload.
-
-**What to do**:
-
-- ❌ **Not done on this branch**: extend the telemetry integration test to
-  start xrpld with `[telemetry] enabled=1` / `[insight] server=otel`, drive RPC
-  and transaction load, query Prometheus for each new metric family and assert
-  non-zero values. The end-to-end metric assertions live in the **Phase 10**
-  harness (`docker/telemetry/workload/expected_metrics.json`), not here.
-
-- ✅ **Done**: unit tests for the `MetricsRegistry` class —
-  `src/tests/libxrpl/telemetry/MetricsRegistry.cpp` (**18** GTest cases —
-  `grep -cE '\bTEST(_F|_P)?\s*\(' src/tests/libxrpl/telemetry/MetricsRegistry.cpp`
-  = 18, and the four bullets below sum to 4 + 3 + 5 + 6 = 18):
-  - Callback registration / deregistration and shutdown ordering —
-    `async_gauges_start_after_start_is_safe`,
-    `async_gauges_before_start_does_not_break_start`,
-    `async_gauges_respect_the_compile_time_guard`, `destructor_calls_stop`
-  - Graceful behaviour when telemetry is disabled — `disabled_construction`,
-    `disabled_start_stop`, `disabled_recording_methods`
-  - Label sanitisation and mean scaling — `MetricsRegistrySanitiseHandler` (5
-    cases, incl. `output_domain_is_exactly_44_values`) and
-    `MetricsRegistryScaledMean` (6 cases)
-  - ❌ Not covered: asserting metric values match `get_counts` JSON output —
-    that needs a live `Application`, so it is left to the Phase 10 harness
-
-**Key files**:
-
-- `src/tests/libxrpl/telemetry/MetricsRegistry.cpp` (new). The originally
-  planned `src/test/telemetry/MetricsRegistry_test.cpp` was **never created** —
-  Phase 9 tests are GTest under `src/tests/libxrpl/`, per project convention.
-- `src/tests/libxrpl/telemetry/MetricMacros.cpp`, `GetMeter.cpp` (new — cover
-  the `XRPL_METRIC_*` macros and meter lookup)
-
----
-
-## Task 9.11: Validator Health Dashboard (External Dashboard Parity)
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity) — dashboards for Phase 7 metrics inspired by the community [xrpl-validator-dashboard](https://github.com/realgrapedrop/xrpl-validator-dashboard).
->
-> **Upstream**: Phase 7 Tasks 7.9-7.16 (metrics must be emitting).
-> **Downstream**: Phase 10 (dashboard load checks), Phase 11 (alert rules reference these panels).
-
-**Objective**: Create a Grafana dashboard for validation agreement, amendment/UNL health, and state tracking.
-
-**Dashboard**: `validator-health.json`
-
-| Panel                      | Type       | PromQL                                                   |
-| -------------------------- | ---------- | -------------------------------------------------------- |
-| Agreement % (1h)           | stat       | `validation_agreement{metric="agreement_pct_1h"}`        |
-| Agreement % (24h)          | stat       | `validation_agreement{metric="agreement_pct_24h"}`       |
-| Agreements vs Missed (1h)  | bargauge   | `agreements_1h` and `missed_1h` side by side             |
-| Agreements vs Missed (24h) | bargauge   | `agreements_24h` and `missed_24h` side by side           |
-| Validation Rate            | stat       | `rate(validations_sent_total[5m]) * 60`                  |
-| Validations Checked Rate   | stat       | `rate(validations_checked_total[5m]) * 60`               |
-| Amendment Blocked          | stat       | `validator_health{metric="amendment_blocked"}`           |
-| UNL Expiry (days)          | stat       | `validator_health{metric="unl_expiry_days"}`             |
-| Validation Quorum          | stat       | `validator_health{metric="validation_quorum"}`           |
-| State Value Timeline       | timeseries | `state_tracking{metric="state_value"}`                   |
-| Time in Current State      | stat       | `state_tracking{metric="time_in_current_state_seconds"}` |
-| State Changes Rate         | stat       | `rate(state_changes_total[1h])`                          |
-| Ledgers Closed Rate        | stat       | `rate(ledgers_closed_total[5m]) * 60`                    |
-
-**Dashboard conventions**: `$node` template variable for `service_instance_id` filtering, dark theme, matching existing panel sizes and color schemes.
-
-**Key new files**: `docker/telemetry/grafana/dashboards/validator-health.json`
-(uid `validator-health`). The name reached its current form in **two** renames:
-`dashboards/rippled-validator-health.json` → `xrpld-validator-health.json`
-(`145b1469d6`, the `dashboards/rippled-*` → `xrpld-*` pass), then
-`xrpld-validator-health.json` → `validator-health.json` (`25868f2740`, which
-dropped the `xrpld-` prefix).
-
-**Exit Criteria**:
-
-- [x] Dashboard ships **17** panels (4 more than the 13 planned above) across 3
-      rows — Validation Agreement, Validation Rates, Server State & Consensus
-- [ ] All panels render with non-zero data during normal operation — needs a live
-      stack; the Phase 10 harness asserts the dashboard _loads_, not that panels
-      are non-empty
-- [x] `$node` filter works correctly for multi-node deployments — `node`
-      template variable present (filters on `service_instance_id`), alongside
-      `service_name`, `deployment_environment`, `xrpl_network_type`,
-      `xrpl_work_item`, `xrpl_branch`, `xrpl_node_role`
-- [x] Amendment blocked and UNL expiry panels use color thresholds
-      (red=blocked/expiring) — 11 `thresholds` blocks in the dashboard JSON
-
----
-
-## Task 9.12: Peer Quality Dashboard (External Dashboard Parity)
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Create a Grafana dashboard for peer health aggregates.
-
-**Dashboard**: `peer-quality.json`
-
-| Panel                  | Type       | PromQL                                                                  |
-| ---------------------- | ---------- | ----------------------------------------------------------------------- |
-| P90 Peer Latency       | timeseries | `peer_quality{metric="peer_latency_p90_ms"}`                            |
-| Insane/Diverged Peers  | stat       | `peer_quality{metric="peers_insane_count"}`                             |
-| Higher Version Peers % | stat       | `peer_quality{metric="peers_higher_version_pct"}`                       |
-| Upgrade Recommended    | stat       | `peer_quality{metric="upgrade_recommended"}`                            |
-| Resource Disconnects   | timeseries | `server_info{metric="peer_disconnects_resources"}`                      |
-| Inbound vs Outbound    | bargauge   | `peer_finder_active_inbound_peers`, `peer_finder_active_outbound_peers` |
-
-> `overlay_peer_disconnects_charges` (the name in the original spec) is **not a
-> real instrument** — nothing registers it. The shipped panel reads
-> `server_info{metric="peer_disconnects_resources"}` instead. Peer-finder gauge
-> names are lowercase: `GroupImp::makeName()` + `OTelCollectorImp::formatName()`
-> turn the `"Peer_Finder"` group into `peer_finder_<name>` with no prefix.
-
-**Key new files**: `docker/telemetry/grafana/dashboards/peer-quality.json`
-(uid `peer-quality`). Two renames, same as Task 9.11:
-`dashboards/rippled-peer-quality.json` → `xrpld-peer-quality.json`
-(`145b1469d6`), then `xrpld-peer-quality.json` → `peer-quality.json`
-(`25868f2740`).
-
-**Exit Criteria**:
-
-- [x] All 6 panels present — P90 Peer Latency, Insane/Diverged Peers, Higher
-      Version Peers %, Upgrade Recommended, Inbound vs Outbound Peers, Resource
-      Disconnects — across 3 rows, with the `$node` template variable
-- [ ] All 6 panels render with data — needs a live stack
-- [x] P90 latency panel is a `timeseries` (shows trend over time)
-- [x] Upgrade recommended panel uses color threshold (red=1, green=0) — 5
-      `thresholds` blocks in the dashboard JSON
-
----
-
-## Task 9.13: Ledger Economy Dashboard Panels (External Dashboard Parity)
-
-> **Source**: [External Dashboard Parity](./06-implementation-phases.md#appendix-external-dashboard-parity)
-
-**Objective**: Add "Ledger Economy" row to the existing `node-health.json` dashboard.
-
-| Panel                | Type       | PromQL                                        |
-| -------------------- | ---------- | --------------------------------------------- |
-| Base Fee (drops)     | stat       | `ledger_economy{metric="base_fee_xrp"}`       |
-| Reserve Base (drops) | stat       | `ledger_economy{metric="reserve_base_xrp"}`   |
-| Reserve Inc (drops)  | stat       | `ledger_economy{metric="reserve_inc_xrp"}`    |
-| Ledger Age           | stat       | `ledger_economy{metric="ledger_age_seconds"}` |
-| Transaction Rate     | timeseries | `ledger_economy{metric="transaction_rate"}`   |
-
-**Key modified files**: `docker/telemetry/grafana/dashboards/node-health.json`
-
-**Exit Criteria**:
-
-- [x] 5 new panels present in the existing dashboard — a "Ledger Economy" row
-      with 5 `ledger_economy` queries is on `node-health.json`
-- [ ] Fee values match `server_info` RPC output — needs a live comparison
-- [ ] Transaction rate shows smooth trend (not spiky) — needs a live run
-
----
-
-## Task 9.14: Overlay Traffic Accounting Defects (Documentation Only)
-
-> **Status**: DOCUMENTED, NOT FIXED. Reference: [09 §6.0-§6.2](./09-data-collection-reference.md#6-known-issues)
-
-**Objective**: Record four pre-existing overlay traffic-accounting defects so
-dashboard readers are not misled. All four originate in `develop`-owned overlay
-files, so **no code fix lands on this branch**.
-
-| #   | Defect                                 | Effect                                                                                    | Fix location (NOT this branch)                   |
-| --- | -------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| 1   | `mtCLUSTER` missing from `kTypeLookup` | `overhead_cluster_*` always zero; 8 panels flatline; cluster traffic counted as `unknown` | `TrafficCount.cpp:11-27`                         |
-| 2   | Stale `Total` header comment           | Claims uncategorized traffic is excluded; it is included                                  | `TrafficCount.h:28-31`                           |
-| 3   | `SquelchIgnored` reported with size 0  | `squelch_ignored_bytes_*` always zero, inconsistent with `SquelchSuppressed`              | `OverlayImpl.cpp:1460,1489` (+ signature change) |
-| 4   | In/out byte-basis asymmetry            | `_bytes_in` vs `_bytes_out` not comparable under compression                              | `PeerImp.cpp:1079` vs `:313`                     |
-
-**Why deferred**: Defect 3 requires widening the two
-`OverlayImpl::updateSlotAndSquelch` overloads — a public signature change on
-shared overlay code. Defects 1 and 4 need `TrafficCount.cpp` and `PeerImp.cpp`
-edits that are not telemetry-owned. Routing them through the telemetry chain
-would hide overlay changes from overlay reviewers and couple them to a 12-PR
-merge timeline.
-
-> **Constraint narrowed.** The blanket "no telemetry change may touch
-> `TrafficCount.{h,cpp}`" no longer holds for the header: the telemetry chain
-> already edits `TrafficCount.h` — Phase 6's `77f35c03db` fixed the
-> `Category::GetFetchPack` label from `"getobject_Fetch Pack_get"` to
-> `"getobject_Fetch_Pack_get"` at `TrafficCount.h:285`, the sole difference from
-> `develop`. Defect 2 (the stale `Total` header comment, `TrafficCount.h:28-31`)
-> is therefore **unblocked** and can land here. Defects **1, 3 and 4** stay
-> blocked: defect 1 needs `TrafficCount.cpp`'s `kTypeLookup`, defect 3 needs the
-> `OverlayImpl` signature change, and defect 4 needs `PeerImp.cpp:1079` vs `:313`
-> to agree on a byte basis (compressed vs uncompressed) — a change to overlay
-> accounting semantics, not telemetry.
-
-**Key modified files**: `OpenTelemetryPlan/09-data-collection-reference.md` only.
-
-**Exit Criteria**:
-
-- [x] Each defect documented with file:line evidence in `09` §6
-- [x] `overhead_cluster_*` documented as "no data", not "no cluster traffic"
-- [ ] Defect 2 (stale `Total` header comment, `TrafficCount.h:28-31`) fixed on
-      this branch — it is **unblocked** (the chain already edits
-      `TrafficCount.h`) but the comment is still uncorrected
-- [ ] Follow-up overlay-owned branch raised for the three still-blocked code
-      fixes (defects 1, 3, 4)
-- [ ] Re-baseline any threshold keyed on `unknown_bytes_in` when defect 1 lands
-
----
-
-## Task 9.15: Peer Keepalive and Discovery Instrumentation
-
-> **Status**: NOT IMPLEMENTED. The instruments themselves are still to be
-> written; the _permission_ question is settled. Reference:
-> [09 §6.3](./09-data-collection-reference.md#63-peer-keepalive-and-discovery-traffic-gaps-not-implemented)
->
-> **Blocker cleared.** This task used to be held "awaiting a decision on whether
-> `XRPL_METRIC_*` call sites may be added to
-> `src/xrpld/overlay/detail/PeerImp.cpp` from this branch". That decision is
-> de facto **yes** — `PeerImp.cpp` already carries **7** such call sites on this
-> branch (`:2723`, `:2741`, `:2925`, `:2928`, `:2931`, `:2947`, `:2954`, of which
-> three are `XRPL_METRIC_HISTOGRAM_RECORD` — `:2925`, `:2928`, `:2931` — and four
-> are labelled counters — `:2723`, `:2741`, `:2947`, `:2954`). Note that
-> `grep -c XRPL_METRIC src/xrpld/overlay/detail/PeerImp.cpp` returns 8: the eighth
-> hit is the `cspell:ignore` explanation comment at `PeerImp.cpp:2`, not a call
-> site. What remains is the implementation work below, not an approval.
-
-**Objective**: Make peer keepalive and peer-discovery health observable. Today
-`mtPING`, `mtSTATUS_CHANGE` and `mtENDPOINTS` are byte counters only.
-
-| Proposed metric                 | Type      | Labels                           | Record site                                         |
-| ------------------------------- | --------- | -------------------------------- | --------------------------------------------------- |
-| `peer_ping_rtt_ms`              | Histogram | none (see note)                  | `PeerImp.cpp:1150-1163`, where the EWMA is computed |
-| `peer_ping_timeouts_total`      | Counter   | `reason="timeout"\|"bad_cookie"` | `PeerImp.cpp:762` and `:1146`                       |
-| `peer_endpoints_received_total` | Counter   | `result="accepted"\|"malformed"` | `PeerImp.cpp:1265-1270`                             |
-
-**Design notes / open questions**:
-
-- A histogram needs an explicit bucket view: the SDK default tops out at 10000,
-  and these are milliseconds. Follow the µs-ladder precedent in
-  `MetricsRegistry.cpp` (see [09 § GetObject Request Path](./09-data-collection-reference.md#getobject-request-path-synchronous-countershistograms)).
-- `peer_id` as a label is unbounded cardinality — rejected. A bounded
-  `peer_role`-style label is the alternative if per-peer attribution is needed.
-- Splitting `mtPING` out of `Category::Base` is a `TrafficCount.cpp` change and
-  therefore still blocked with Task 9.14 defect 1. (The `.h` half of that
-  constraint no longer applies — see Task 9.14.)
-- Per the runbook's "Adding a New Metric" contract, `_total` is reserved for
-  monotonic counters; a histogram takes no suffix.
-
-**Key files (if approved)**: `src/xrpld/overlay/detail/PeerImp.cpp`,
-`09-data-collection-reference.md`, `docs/telemetry-runbook.md` § Metric Reference,
-`docker/telemetry/grafana/dashboards/peer-quality.json`, and
-`docker/telemetry/workload/expected_metrics.json` (**Phase 10 branch**).
-
-**Exit Criteria**:
-
-- [x] Decision recorded on editing `PeerImp.cpp` from the telemetry chain — yes;
-      7 `XRPL_METRIC_*` call sites already ship in `PeerImp.cpp`
-- [ ] Three instruments emitting, with an explicit histogram bucket view
-- [ ] Rows added to `09` §5b, runbook § Metric Reference, and `expected_metrics.json`
-- [ ] Peer Quality dashboard panels follow the Task 9.12 conventions (`$node`, Title Case, legend dimensions)
-- [ ] `check_otel_naming.py` passes (Rules D and E cover the new labels)
-
----
-
-## Task 9.16: PeerFinder Slot and Cache Metrics
-
-> **Status**: NOT IMPLEMENTED. Reference: [09 §6.5](./09-data-collection-reference.md#65-peerfinder-slot-and-cache-metrics-not-implemented)
-
-**Objective**: Export the PeerFinder slot counts and discovery-cache sizes.
-Only 2 of ~17 available readings are exported today.
-
-**What to do**: Extend the existing `Stats` struct in
-`src/libxrpl/peerfinder/PeerfinderManager.cpp:227-236` with gauges for the
-`Counts` accessors listed in [09 §6.5](./09-data-collection-reference.md#65-peerfinder-slot-and-cache-metrics-not-implemented)
-(slot caps and frees, attempt counts, handshake pipeline depth, fixed-peer state,
-network reachability), plus `Livecache::size()` and `Bootcache::size()`.
-
-**Pipeline constraint**: `PeerfinderManager.cpp` is in `libxrpl`, which **cannot**
-use the `XRPL_METRIC_*` macros. These must go through `beast::insight` —
-arrow **B**, not **C**. Naming follows `GroupImp::makeName()` +
-`OTelCollectorImp::formatName()`, so the `"Peer_Finder"` group yields
-`peer_finder_<name>` lowercased.
-
-**Known obstacle**: `Livecache` and `Bootcache` hold no collector reference, so
-their sizes must either be read through the existing `Manager` hook or have a
-collector plumbed in.
-
-**Exit Criteria**:
-
-- [ ] Slot caps exported so utilization (`active / max`) is computable
-- [ ] Both cache sizes exported
-- [ ] "Inbound vs Outbound" panel on `peer-quality` extended to show utilization %
-- [ ] Rows added to `09` §2.1, runbook § Metric Reference, `expected_metrics.json` (Phase 10)
-
----
-
-## Task 9.17: Peer Span Coverage (Deferred to Phase 11)
-
-> **Status**: NOT IMPLEMENTED — design only, pending approval. Reference:
-> [09 §6.4](./09-data-collection-reference.md#64-peer-span-coverage-gap-not-implemented)
-> and [02 §2.3.2](./02-design-decisions.md#232-complete-span-catalog)
-
-**Objective**: Close the gap between the `02` §2.3.2 span catalog and what
-actually emits. `peer.connect`, `peer.disconnect`, `peer.message.send` and
-`peer.message.receive` were catalogued from the start and never built; 11 of 13
-protocol message families have no spans.
-
-**Scope warning**: This is larger than Tasks 9.14-9.16 combined and changes the
-span-family inventory asserted in `09` §1.1 (**41** emitted families) and in
-`docker/telemetry/workload/expected_spans.json` (**40** catalogued — `rpc.ws_upgrade`
-has no entry). `trace_peer` is also **on by default** and already flagged as
-high-volume, so adding per-message spans has a volume cost that needs measuring
-before commitment.
-
-**Exit Criteria**:
-
-- [x] `02` §2.3.2 marked Live / Not built / Renamed against the real inventory
-- [ ] User approval to proceed with span implementation
-- [ ] Volume impact measured under `trace_peer=1` before any span is added
-
----
-
-## Exit Criteria
-
-- [ ] All ~50 new metrics visible in Prometheus via OTLP pipeline — every
-      instrument is registered in `MetricsRegistry.cpp`, but end-to-end
-      visibility is asserted only by the Phase 10 harness
-- [x] `MetricsRegistry` class registers/deregisters cleanly with OTel SDK —
-      `src/tests/libxrpl/telemetry/MetricsRegistry.cpp`
-      (`async_gauges_start_after_start_is_safe`,
-      `async_gauges_before_start_does_not_break_start`,
-      `async_gauges_respect_the_compile_time_guard`, `destructor_calls_stop`)
-- [x] Async gauge callbacks execute at 10s intervals —
-      `MetricsRegistry.cpp:289`, `readerOpts.export_interval_millis = 10000`.
-      (The "without performance impact" half is unmeasured — see below.)
-- [x] 4 new Grafana dashboards operational (Fee Market, Job Queue, Validator
-      Health, Peer Quality) — all four JSONs are under
-      `docker/telemetry/grafana/dashboards/`
-- [x] 2 existing dashboards updated with new panel groups — `node-health`
-      (NodeStore I/O, Caches, Server Info, Complete Ledgers & DB, Ledger
-      Economy, Job Queue Concurrency Limits rows) and `rpc-performance`
-      (per-method section)
-- [ ] Integration test validates all new metric families are non-zero — not on
-      this branch; lives in the Phase 10 harness (`expected_metrics.json`)
-- [ ] No performance regression (< 0.5% CPU overhead from new callbacks) — not
-      measured; needs the Phase 10 benchmark suite
-- [x] Documentation updated with full new metric inventory —
-      `09-data-collection-reference.md` §5b + "Phase 9: OTel SDK-Exported
-      Metrics (MetricsRegistry)" + "Phase 7+: External Dashboard Parity Metrics"
-- [x] Validator Health dashboard ships (17 panels, 4 more than the 13 planned)
-- [x] Peer Quality dashboard ships (6 panels)
-- [x] Ledger Economy panels added to node-health dashboard (5 panels in a
-      "Ledger Economy" row)
-- [x] Provisioned Grafana alerting: 13 rules / 5 groups, 2 contact points,
-      nested notification policy
-- [ ] Tasks 9.14-9.17 closed — **open by design**: 9.14 documented-not-fixed
-      (defects 1, 3 and 4 still blocked; defect 2 unblocked but not yet fixed),
-      9.15 and 9.16 not implemented, 9.17 deferred pending approval and volume
-      measurement
-
----
-
-## Appendix: Alerting Design
-
-> Design for the provisioned Grafana alert rules (Task 9.9a). Previously a standalone spec; merged here so the phase plan is self-contained.
-
-**Date:** 2026-07-06
-**Branch:** `pratik/otel-phase9-metric-gap-fill` (PR #6513)
-**Status:** Approved
-
-### Purpose
-
-Phase 9 exports ~68 internal xrpld metrics and ships Grafana dashboards for
-them. This adds the missing operator-facing piece: **provisioned Grafana alert
-rules** that fire on the health-critical metrics phase 9 introduces. The
-phase-9 task list already lists "alerting rules" as a phase-9 deliverable
-(Task 9.9), so this closes that gap.
-
-Scope is deliberately narrow — the three subsystems whose failure is
-node-fatal: **consensus/ledger health, validator health, job queue**. RPC/API
-health is explicitly out of scope.
-
-### Why phase 9 (not phase 11)
-
-Every metric these alerts fire on is _born_ in phase 9
-(`ledger_history_mismatch_total`, `ledgers_closed_total`,
-`validation_missed_total`, `validations_checked_total`,
-`jq_trans_overflow_total`, `job_queued_us_bucket` — the histogram instrument is
-`job_queued_us` (`MetricsRegistry.cpp:94`), so the Prometheus bucket series is
-`job_queued_us_bucket`, not `job_queued_duration_us_bucket`). Alerts
-belong with the metrics they watch, and this is where the dependency lives.
-
-### Delivery
-
-Provisioned YAML, version-controlled — matching the existing datasource /
-dashboard provisioning pattern. No docker-compose change: the Grafana service
-already mounts `./grafana/provisioning:/etc/grafana/provisioning:ro`, and
-Grafana auto-loads `provisioning/alerting/*.yaml`.
-
-New files under `docker/telemetry/grafana/provisioning/alerting/`:
-
-| File                 | Purpose                                                                                                                                                                                                                      |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `contactpoints.yaml` | **Two** contact points: `xrpld-default` (Slack) and `xrpld-critical` (Slack + email).                                                                                                                                        |
-| `policies.yaml`      | **Nested** notification policy: root route → `xrpld-default`; child route matching `severity = critical` → `xrpld-critical` (`repeat_interval: 1h` vs the root's `4h`). Both grouped by `alertname` + `service_instance_id`. |
-| `rules.yaml`         | **13** alert rules across **5** groups (below).                                                                                                                                                                              |
-
-Plus the Alerting section of `docs/telemetry-runbook.md` — operator runbook:
-what each alert means, likely causes, and how to point the contact point at a
-real receiver.
-
-### Alert rules
-
-All rules target Prometheus datasource `uid: prometheus`. Each rule uses the
-Grafana rule shape: query (A) → reduce (B, last value) → threshold (C). All
-`rate()`/`histogram_quantile()` expressions aggregate with
-`sum by (service_instance_id)` (or `+ le`) so **each node alerts independently**.
-Alert rules run headless, so they cannot use the dashboards' `$node` template
-variables — they match all series and group by `service_instance_id` instead.
-
-All 5 groups evaluate at `interval: 1m`. Metric names carry **no** `xrpld_`
-prefix — `OTelCollectorImp::formatName()` adds none.
-
-The **Threshold** column is the rule's refId `C` evaluator, read straight from
-`rules.yaml` — it is the firing condition, so it is load-bearing, not decoration.
-
-| Group              | Alert                   | Expression (refId A)                                                                                      | Threshold (refId C)                               | `for` | severity |
-| ------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ----- | -------- |
-| `xrpld-consensus`  | LedgerHistoryMismatch   | `sum by (service_instance_id) (increase(ledger_history_mismatch_total[15m]))`                             | `gt [0]`                                          | 2m    | critical |
-| `xrpld-consensus`  | LedgerCloseStalled      | `rate(ledgers_closed_total)` decayed to ≈0                                                                | `lt [0.001]`                                      | 3m    | critical |
-| `xrpld-consensus`  | ValidatedLedgerStale    | `max by (service_instance_id) (ledgermaster_validated_ledger_age < 1209600)`                              | `gt [60]` (seconds)                               | 5m    | critical |
-| `xrpld-validator`  | ValidationsMissed       | miss **ratio**, gated on send activity — see the expression below the table                               | `gt [0.1]`                                        | 15m   | warning  |
-| `xrpld-validator`  | ValidationsNotChecked   | `rate(validations_checked_total)` ≈0                                                                      | `lt [0.001]`                                      | 5m    | warning  |
-| `xrpld-jobqueue`   | JobQueueTxOverflow      | `sum by (service_instance_id) (increase(jq_trans_overflow_total[15m]))`                                   | `gt [0]`                                          | 2m    | warning  |
-| `xrpld-jobqueue`   | JobQueueLatencyHigh     | `histogram_quantile(0.99, sum by (le, service_instance_id) (rate(job_queued_us_bucket[5m])))`             | `gt [1000000]` (µs = 1s)                          | 5m    | warning  |
-| `xrpld-jobqueue`   | NodeStoreIOLatencyHigh  | `histogram_quantile(0.95, sum by (le, service_instance_id) (rate(ios_latency_milliseconds_bucket[10m])))` | `gt [1000]` (ms)                                  | 10m   | warning  |
-| `xrpld-node-state` | NodeStateFlapping       | state-transition rate over the node-state series                                                          | `gt [3]` (transitions)                            | 15m   | warning  |
-| `xrpld-node-state` | NodeNotFull             | operating mode below FULL                                                                                 | `lt [4]` (FULL = 4)                               | 15m   | warning  |
-| `xrpld-overlay`    | ManifestJobQueueConvoy  | `sum by (service_instance_id) (jobq_manifest_waiting)`                                                    | `gt [3]` (waiting jobs)                           | 10m   | warning  |
-| `xrpld-overlay`    | ManifestFloodInbound    | inbound manifest byte rate                                                                                | `gt [524288]` (B/s = 512 **KiB**/s, not 512 kB/s) | 10m   | warning  |
-| `xrpld-overlay`    | PeerResourceDisconnects | `sum by (service_instance_id) (increase(server_info{metric="peer_disconnects_resources"}[30m]))`          | `gt [5]`                                          | 5m    | warning  |
-
-**`ValidationsMissed` is a gated ratio, not `rate(...) > 0`.** The raw-rate shape
-is the pre-fix version and it fires on **every non-validating node**:
-`ValidationTracker` counts a miss whenever `weValidated && networkValidated` is
-not both true, and a non-validator never sets `weValidated`, so its measured
-ratio is exactly **1.0**. No threshold can separate "not a validator" from
-"validator disagreeing", hence the `and on (...)` activity gate. The shipped
-expression is:
-
-- numerator: `sum by (service_instance_id) (rate(validation_missed_total[15m]))`
-- denominator: `clamp_min(` that same numerator `+ sum by (service_instance_id) (rate(validation_agreements_total[15m])), 1e-9)`
-- gate: `and on (service_instance_id) (sum by (service_instance_id) (rate(validations_sent_total[15m])) > 0)`
-- evaluator: `gt [0.1]` — i.e. >10% disagreement among nodes that do validate
-
-3 rules are `severity: critical`, 10 are `severity: warning`.
-
-Each rule carries labels `severity` and `category`
-and annotations `summary` + `description` (with `{{ $labels.service_instance_id }}`
-and `{{ $values.B.Value }}` interpolation).
-
-#### Threshold rationale
-
-- **LedgerCloseStalled `< 0.001` for 3m**: healthy nodes close a ledger every
-  ~3-5s; a 5m rate decaying to ~0 means the node is stuck. The epsilon (not
-  exact `0`) avoids float rate-noise suppressing the alert.
-- **JobQueueLatencyHigh 1s p99**: `gt [1000000]` µs = 1s. A default starting
-  point, easy to tune — jobs queued >1s at p99 indicate the node is saturated.
-- **ValidationsMissed `> 0.1` on a gated ratio**, not `> 0` on a raw rate: the
-  raw rate is permanently nonzero (ratio 1.0) on non-validators, so a `> 0` rule
-  pages on every non-validating node in the fleet. See the note above the
-  rationale list.
-- **ManifestFloodInbound 524288 B/s**: an earlier 50 kB/s threshold produced ~41
-  sustained 5-minute samples on healthy nodes; 512 KiB/s clears normal
-  manifest-exchange peaks.
-- Remaining `gt [0]` rules (`LedgerHistoryMismatch`, `JobQueueTxOverflow`) sit on
-  true error counters where any sustained nonzero rate is actionable.
-
-### Non-goals / YAGNI
-
-- No per-alert silencing schedules, no mute timings.
-- No RPC/API or fee-market alerts (dashboards cover those visually). Overlay
-  alerts _were_ added during implementation — the `xrpld-overlay` group carries
-  three (manifest convoy, manifest flood, peer resource disconnects).
-- Two contact points and a two-level policy tree shipped; deeper routing
-  (Discord, PagerDuty, per-team splits) is left to the operator.
-
-### Verification
-
-1. `yamllint` (or `python -c yaml.safe_load`) on all three YAML files.
-2. `docker compose -f docker/telemetry/docker-compose.yml config -q` still parses.
-3. Optional live check: start stack, `GET /api/v1/provisioning/alert-rules`
-   returns the 13 rules; Grafana logs show no provisioning errors.
-4. Code-review pass (subagent) against phase conventions before commit.

OpenTelemetryPlan/secure-OTel.md

@@ -1,240 +0,0 @@
-# Securing OpenTelemetry Against Trace Context Spoofing
-
-> **Part of**: [OpenTelemetry Implementation Plan](./OpenTelemetryPlan.md) — see also [Design Decisions § Privacy](./02-design-decisions.md#244-privacy--sensitive-data-policy) (what we don't collect) and [Configuration Reference § 5.5](./05-configuration-reference.md#55-opentelemetry-collector-configuration) (collector base config).
-
-Trace context spoofing (or poisoning) occurs when untrusted actors inject tampered or stale trace IDs into your system. If these requests are processed, the spans are appended to historical trace buckets, stretching trace durations, ruining p99 latency metrics, and breaking Grafana dashboards.
-
-This guide outlines two categories of defense: mitigating tampered contexts and locking down the OpenTelemetry (OTel) Collector to trusted clients only.
-
----
-
-## Part 1: Mitigating Tampered Trace Contexts
-
-### 1. Perimeter Defense: Strip Headers at the API Gateway
-
-The most effective way to prevent spoofing from external sources is to treat your API Gateway (Envoy, NGINX, AWS ALB) as a hard boundary. Strip incoming W3C tracing headers (`traceparent`, `tracestate`) from public traffic so the gateway is forced to generate a fresh, legitimate `trace_id`.
-
-**NGINX Example (Stripping Headers):**
-
-```nginx
-server {
-    listen 80;
-
-    location / {
-        # Clear out untrusted incoming trace headers
-        proxy_set_header traceparent "";
-        proxy_set_header tracestate "";
-
-        proxy_pass http://backend_service;
-    }
-}
-```
-
-### **2. Timestamp-Anchored Trace IDs and OTTL Filtering**
-
-If you use a custom trace ID generator that embeds a timestamp in the first few bytes (like AWS X-Ray or UUIDv7), you can use the OTel Collector's OpenTelemetry Transform Language (OTTL) to detect anomalies.
-**Collector Configuration (Conceptual OTTL Filter):**
-
-```yaml
-processors:
-  filter/stale_traces:
-    error_mode: ignore
-    traces:
-      span:
-        # Example: Drop spans where the start time is significantly different
-        # from an expected parameter or embedded timestamp logic.
-        # Note: Standard W3C trace IDs do not contain timestamps by default.
-        - 'Keep out-of-bounds spans: time.sub(start_time, now()) > duration("1h")'
-```
-
-## **Part 2: Restricting Access to the OTel Collector**
-
-Locking down the Collector ensures that only authenticated, trusted clients can submit telemetry data.
-
-### **Approach A: Network Layer Security (Kubernetes Network Policies)**
-
-Ensure your Collector is not exposed to the public internet. If running in Kubernetes, use a NetworkPolicy to restrict ingress traffic to specific namespaces.
-**Kubernetes NetworkPolicy Example:**
-
-```yaml
-apiVersion: networking.k8s.io/v1
-kind: NetworkPolicy
-metadata:
-  name: allow-internal-otel
-  namespace: observability
-spec:
-  podSelector:
-    matchLabels:
-      app: opentelemetry-collector
-  policyTypes:
-    - Ingress
-  ingress:
-    - from:
-        - namespaceSelector:
-            matchLabels:
-              environment: production
-      ports:
-        - protocol: TCP
-          port: 4317 # gRPC
-        - protocol: TCP
-          port: 4318 # HTTP
-```
-
-### **Approach B: Transport Layer Security (Mutual TLS / mTLS)**
-
-Require clients to present a valid cryptographic certificate to connect to the Collector.
-**Collector Configuration (mTLS):**
-
-```yaml
-receivers:
-  otlp:
-    protocols:
-      grpc:
-        endpoint: 0.0.0.0:4317
-        tls:
-          # Setting client_ca_file makes the collector require and verify a
-          # client cert, rejecting connections without a trusted one.
-          client_ca_file: /certs/client_ca.pem # CA that signs trusted client certs
-          cert_file: /certs/collector.pem
-          key_file: /certs/collector.key
-```
-
-### **Approach C: Application Layer Authentication (Basic Auth Extension)**
-
-Use the Collector's extension system to require an API key or Basic Auth credentials.
-**Collector Configuration (Basic Auth):**
-
-```yaml
-extensions:
-  basicauth/collector:
-    htpasswd:
-      inline: |
-        # username:trusted-client, password:SecurePassword123
-        trusted-client:$apr1$4v8p76o6$DMTX5Wv6uOmrFAZp2X1N1.
-
-receivers:
-  otlp:
-    protocols:
-      grpc:
-        endpoint: 0.0.0.0:4317
-        auth:
-          authenticator: basicauth/collector
-
-processors:
-  batch:
-
-exporters:
-  otlp:
-    endpoint: my-backend-storage:4317
-
-service:
-  extensions: [basicauth/collector]
-  pipelines:
-    traces:
-      receivers: [otlp]
-      processors: [batch]
-      exporters: [otlp]
-```
-
-**Client Setup (Environment Variables):**
-Developers must pass the authentication header using the standard OTel SDK environment variables:
-
-```bash
-# Base64 encoded "trusted-client:SecurePassword123"
-export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic dHJ1c3RlZC1jbGllbnQ6U2VjdXJlUGFzc3dvcmQxMjM="
-```
-
----
-
-Available routes to build on top of: https://github.com/XRPLF/rippled/pull/6425#discussion_r3234751995
-
----
-
-# Analysis: Applying the Guide to xrpld
-
-The guide above is written for HTTP-fronted web services. xrpld is a P2P node daemon, so the threat model and the applicable defenses differ. This section captures how each approach maps to xrpld and the chosen direction.
-
-## Threat Model
-
-xrpld has **two distinct attack surfaces**, not one. The original guide conflates them under "trace context spoofing"; for xrpld they need separate defenses.
-
-| Surface                                   | Attacker                                                 | Vector                                                                                                                                                                                     | Defense                                       |
-| ----------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
-| **Collector ingress** (xrpld → collector) | Anyone who can reach `4317`/`4318` on the collector host | Forged OTLP traffic, telemetry exfiltration, DoS on collector                                                                                                                              | mTLS + network policy                         |
-| **Peer trace context** (peer → xrpld)     | Malicious peer in the XRPL overlay                       | Crafted `protocol::TraceContext` field inside peer protobuf messages (TMTransaction, consensus, etc.) — used to forge `trace_id`/`span_id`, pollute p99, attach spans to historical traces | Validate + rate-limit at the receive boundary |
-
-**Deployment context:** Across-network. xrpld nodes (potentially run by external operators or in different DCs) ship telemetry to a centrally-hosted collector across an untrusted network. The collector is NOT on the same host or private VPC as every node.
-
-```
-                ┌── peer (untrusted) ── TMTransaction{trace_context} ──▶ xrpld
-                │                                                            │
-                │                                              [validate + rate-limit]
-                │                                                            │
-                │                                                            ▼
-                │                                                     SpanGuard (clean)
-                │                                                            │
-                │                                                            │ OTLP/gRPC
-                │                                                            │ + mTLS
-                │                                                            ▼
-                └─────────────────────────────────────────  [client_ca_file: verify client cert]
-                                                                  OTel Collector
-                                                              (in private subnet, NetPol)
-```
-
-## Part 1 Applicability — Peer Trace-Context Validation
-
-The guide's NGINX header stripping and OTTL stale-span filtering target HTTP gateways and post-hoc cleanup. Neither fits xrpld directly:
-
-- **NGINX header stripping** — N/A. There is no HTTP gateway between peers and xrpld; trace context arrives inside protobuf peer messages (`protocol::TraceContext`), not as W3C `traceparent` headers. See [src/xrpld/telemetry/PropagationHelpers.h](../src/xrpld/telemetry/PropagationHelpers.h).
-- **OTTL stale-span filtering** — Weak fit. Post-hoc cleanup at the collector loses peer identity (you can't tell _which_ peer poisoned the trace). Validation at the receive site is stronger.
-
-**xrpld-specific Part 1 mitigations:**
-
-1. **Validate extracted context at the boundary** in [src/xrpld/telemetry/ConsensusReceiveTracing.h](../src/xrpld/telemetry/ConsensusReceiveTracing.h) and any other peer-message receive site. Reject if `trace_id` is all-zero, wrong length, or fails W3C format checks. Treat invalid context as "no propagated context" — start a fresh span — rather than dropping the message.
-2. **Per-peer sample rate limiting** so a hostile peer cannot flood the collector with spans bearing a fabricated `trace_id`. Use probabilistic sampling on the receive path keyed by peer identity.
-
-## Part 2 — Comparison of Collector Hardening Approaches
-
-Evaluated for the across-network deployment shape:
-
-| Approach                        | Across-network fit                                                                                                                                                                                                                                                                                                | Cost                                                                 | Verdict                            |
-| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------- |
-| **A. NetworkPolicy / firewall** | Necessary baseline (don't expose `4317`/`4318` to the internet), but insufficient on its own when traffic genuinely crosses networks — you cannot NetworkPolicy the public internet.                                                                                                                              | Cheap.                                                               | **Defense-in-depth, not primary.** |
-| **B. mTLS**                     | Strongest fit. Every xrpld node holds a client cert; the collector verifies it via `client_ca_file` in the receiver's `tls` block. Encrypts in transit (raw OTLP over the internet leaks transaction patterns and validator identity). Compromised node = revoke one cert, no shared secret to rotate everywhere. | Cert issuance + rotation pipeline.                                   | **Primary.**                       |
-| **C. Basic Auth**               | Worst shape for this topology. Single shared password across all xrpld nodes — one leaked node config compromises the whole fleet. Doesn't encrypt; you'd need TLS underneath anyway, at which point you're 80% of the way to mTLS.                                                                               | Cheap to set up, expensive to operate (rotation across N operators). | **Skip.**                          |
-
-## Decision
-
-**Primary defense:** mTLS (Approach B) on the collector's OTLP receivers. The collector requires and verifies each client certificate when `client_ca_file` is set in the receiver's `tls` block (there is no `auth_type` field — setting `client_ca_file` is what enforces client-cert verification).
-
-**Defense-in-depth:** NetworkPolicy / firewall rules (Approach A) so `4317`/`4318` are never reachable from outside the expected operator subnets even if mTLS were misconfigured.
-
-**Skipped:** Basic Auth (Approach C) — wrong shape for an across-network, multi-operator topology.
-
-**Plus xrpld-specific Part 1 work:** trace-context validation and per-peer rate limiting at peer-message receive sites.
-
-## Decisions Made
-
-| Decision             | Choice                           | Rationale                                                                                                                                                                                                                                                     |
-| -------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Cert source for mTLS | **Reuse XRPL node identity key** | One identity per node, no separate PKI to operate. Fits XRPL's existing trust model; requires small CA tooling step to derive/sign the OTel client cert from the node key.                                                                                    |
-| Part 1 scope         | **Include in this spec**         | Collector hardening and peer trace-context validation share one threat model. Coherent design doc; can still be split into multiple PRs at implementation.                                                                                                    |
-| Dev impact           | **Production-only**              | Local `docker/telemetry/docker-compose.yml` keeps `insecure: true` and no auth for fast iteration. Only production deployment manifests gain mTLS. Accepted risk: minor dev/prod drift, mitigated by integration tests against a TLS-enabled collector in CI. |
-
-## Out of Scope
-
-- NGINX/Envoy header stripping (no HTTP gateway in front of xrpld-to-collector traffic).
-- OTTL stale-span filtering at the collector (weaker than source validation; loses peer identity).
-- Local development docker-compose hardening.
-- Telemetry backend (Tempo) hardening — separate concern, downstream of the collector.
-
-## Next Step
-
-Write this up as a design doc with full sections covering:
-
-1. Threat model & architecture (this section, expanded)
-2. Collector hardening — mTLS config, NetworkPolicy
-3. Cert pipeline — deriving OTel client cert from XRPL node key
-4. Peer trace-context validation — receive-site checks in `ConsensusReceiveTracing.h`
-5. Per-peer span rate limiting
-6. Testing & rollout

README.md

@@ -54,7 +54,6 @@ Here are some good places to start learning the source code:
 | `./docs`   | Source documentation files and doxygen config. |
 | `./cfg`    | Example configuration files.                   |
 | `./src`    | Source code.                                   |
-| `./crates` | Rust source code.                              |
 
 Some of the directories under `src` are external repositories included using
 git-subtree. See those directories' README files for more details.

bin/check-nix-store-refs.sh

@@ -1,111 +0,0 @@
-#!/usr/bin/env bash
-# Fail if a binary under <path> records a /nix/store path it resolves at run
-# time. See docs/build/nix.md#prebuilt-packages for why that matters.
-#
-# <path> is a file or a directory. macOS: nothing may reference the store, so
-# point it at whole trees. Linux: the toolchain always writes the store into
-# PT_INTERP and RUNPATH, so only at what cmake/PatchNixBinary.cmake retargets.
-#
-# Only Mach-O / ELF is inspected. Static archives hold store paths in debug info
-# alone; the scripts in a Conan cache are all git hook samples and autotools
-# scratch, 36 false positives to 0 real.
-#
-# Usage: bin/check-nix-store-refs.sh <path>
-
-set -euo pipefail
-
-if [ "$#" -ne 1 ]; then
-    echo "usage: $0 <path>" >&2
-    exit 2
-fi
-
-if [ ! -e "$1" ]; then
-    echo "$0: no such path: $1" >&2
-    exit 2
-fi
-
-case "$(uname -s)" in
-    Darwin)
-        format=Mach-O
-        recorded_paths=macho_recorded_paths
-        tool=otool
-        ;;
-    Linux)
-        format=ELF
-        recorded_paths=elf_recorded_paths
-        tool=readelf
-        ;;
-    *)
-        echo "Unsupported OS - skipping the Nix store reference check."
-        exit 0
-        ;;
-esac
-
-# `pipefail` would catch this too, but only as a bare nonzero exit.
-if ! command -v "${tool}" >/dev/null; then
-    echo "$0: ${tool} not found; cannot inspect binaries" >&2
-    exit 2
-fi
-
-# Both list what the file records. `ldd` would answer what this machine resolves
-# now, which is wrong both ways: store paths for a correctly patched binary,
-# silence for a store RUNPATH that resolves nowhere.
-
-# `name` covers LC_ID_DYLIB and LC_LOAD*_DYLIB, `path` covers LC_RPATH.
-macho_recorded_paths() {
-    otool -l "$1" | sed -nE 's#^ *(name|path) ([^ ]*).*#\2#p'
-}
-
-# RPATH and RUNPATH are colon-separated.
-elf_recorded_paths() {
-    readelf -ldW "$1" |
-        sed -nE \
-            -e 's#.*program interpreter: ([^]]*)\].*#\1#p' \
-            -e 's#.*\((RPATH|RUNPATH|NEEDED)\).*\[([^]]*)\].*#\2#p' |
-        tr ':' '\n'
-}
-
-checked=0
-skipped=0
-leaked=0
-
-while IFS= read -r file; do
-    case "$(file -b "${file}" 2>/dev/null)" in
-        *"${format}"*) ;;
-        *)
-            skipped=$((skipped + 1))
-            continue
-            ;;
-    esac
-    checked=$((checked + 1))
-
-    # Filter after extracting, or a search path starting elsewhere ($ORIGIN)
-    # hides the rest. `sed` not `grep`: grep calls "no matches" a failure, and
-    # the `|| true` that would need masks a broken pipeline too.
-    refs="$("${recorded_paths}" "${file}" | sed -n '\#^/nix/store/#p' | sort -u)"
-    if [ -n "${refs}" ]; then
-        leaked=$((leaked + 1))
-        echo "::error file=${file}::references the Nix store at run time"
-        echo "${file}"
-        echo "${refs}" | sed 's/^/    /'
-    fi
-done < <(find "$1" -type f \( -perm -u+x -o -name '*.dylib' -o -name '*.so*' \))
-
-echo "$1: checked ${checked}, skipped ${skipped}, ${leaked} with Nix store references."
-
-if [ "${leaked}" -ne 0 ]; then
-    cat >&2 <<'EOF'
-
-Fixes, in order of preference:
-  - A Conan package built before this check existed: drop it
-    (`conan remove '<name>/*'`) and rebuild.
-  - A binary that should have been retargeted to the system loader: check that
-    cmake/PatchNixBinary.cmake ran for it.
-  - Link the macOS system library instead of the Nix one - see
-    libresolvSystemStub in nix/darwin.nix.
-  - No system library exists (libstdc++): link it statically.
-  - None of the above: pin the toolchain into the package ID, following
-    `user.package:libc_version` in conan/profiles/ci.
-EOF
-    exit 1
-fi

bin/check-tools.sh

@@ -15,14 +15,10 @@
 #   - Windows: the core build tools only (CMake, Conan, Git, Python).
 #              MSVC is expected to be provided separately and is not checked here.
 #
-# Some tools (clang-format, clang-tidy, doxygen, gcovr, gh, git-cliff, gpg,
-# pre-commit, run-clang-tidy) are present in our Linux CI images and in local
-# development setups, but not in the macOS CI environment. They are checked
-# everywhere except when running in CI on macOS.
-#
-# Tools that Nix also exposes under a version-suffixed name (`clang-tidy-22`,
-# `g++-15`, ...) are probed under both names: a suffixed name can break while
-# the plain one still works (see mkVersionedToolLinks in nix/packages.nix).
+# Some tools (clang-format, doxygen, gcovr, gh, git-cliff, gpg, pre-commit,
+# run-clang-tidy) are present in our Linux CI images and in local development
+# setups, but not in the macOS CI environment. They are checked everywhere
+# except when running in CI on macOS.
 #
 # Environment variables:
 #   CI                      if set, skip the tools above when on macOS.
@@ -30,27 +26,14 @@
 
 set -uo pipefail
 
-# Version suffixes of the Nix tool links, tracking nix/packages.nix.
-gcc_version=15
-llvm_version=22
-
 missing=()
 checked=0
 
-# tool_path <name>
-# Fully resolved path of a tool, so the snapshots record which derivation
-# provides it. Prints nothing when it isn't on PATH.
-tool_path() {
-    local path
-    path="$(command -v "$1" 2>/dev/null)" || return 0
-    readlink -f "${path}" 2>/dev/null || printf '%s' "${path}"
-}
-
 # check <name> [probe-command...]
 # Runs the probe (default: "<name> --version"), capturing both stdout and
-# stderr, and prints three lines: the status and name, the first non-blank line
-# of the probe output (its version, or the error when it failed), and the tool's
-# resolved path. Records <name> as missing if it is not found or exits non-zero.
+# stderr, and prints one aligned line: the status, the name, and the first
+# non-blank line of the probe output (its version). Records <name> as missing
+# if the command is not found or exits non-zero.
 check() {
     local name="$1"
     shift
@@ -60,17 +43,14 @@ check() {
     fi
 
     checked=$((checked + 1))
-    local output version path
-    path="$(tool_path "${name}")"
+    local output version
     if output="$("${probe[@]}" 2>&1)"; then
-        printf '  ✅ %s\n' "${name}"
+        version="$(printf '%s\n' "${output}" | grep -m1 '[^[:space:]]' || true)"
+        printf '  [ ok ] %-20s %s\n' "${name}" "${version}"
     else
-        printf '  ❌ %s\n' "${name}"
+        printf '  [MISS] %s\n' "${name}"
         missing+=("${name}")
     fi
-    version="$(printf '%s\n' "${output}" | grep -m1 '[^[:space:]]' || true)"
-    printf '     %s\n' "${version:-(no output)}"
-    printf '     %s\n' "${path:-(not found)}"
 }
 
 case "$(uname -s)" in
@@ -102,9 +82,7 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
     echo "Development tooling:"
     check ccache
     check clang
-    check "clang-${llvm_version}"
     check clang++
-    check "clang++-${llvm_version}"
     check ClangBuildAnalyzer
     check curl
     check file
@@ -123,14 +101,7 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
     # setups, but not in the macOS CI environment. So check them everywhere
     # except when running in CI on macOS.
     if [ "${os}" = "linux" ] || [ -z "${CI:-}" ]; then
-        check clang-apply-replacements
-        check "clang-apply-replacements-${llvm_version}"
         check clang-format
-        check "clang-format-${llvm_version}"
-        # clang-tidy leads --version with the LLVM banner, not the version.
-        tidy_probe="--version | grep -m1 -oE 'LLVM version [0-9.]+'"
-        check clang-tidy sh -c "clang-tidy ${tidy_probe}"
-        check "clang-tidy-${llvm_version}" sh -c "clang-tidy-${llvm_version} ${tidy_probe}"
         check dot
         check doxygen
         check gcovr
@@ -141,7 +112,6 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
         # pre-commit, or its alternative implementation prek
         check pre-commit sh -c 'pre-commit --version || prek --version'
         check run-clang-tidy run-clang-tidy --help
-        check "run-clang-tidy-${llvm_version}" "run-clang-tidy-${llvm_version}" --help
     fi
 fi
 
@@ -156,7 +126,7 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
     check cargo-audit cargo audit --version
     check cargo-llvm-cov cargo llvm-cov --version
     check cargo-nextest cargo nextest --version
-    check clippy-driver
+    check clippy clippy-driver --version
     check rust-analyzer
     check rustc
     check rustfmt
@@ -168,11 +138,7 @@ if [ "${os}" = "linux" ]; then
     echo
     echo "GCC toolchain:"
     check gcc
-    check "gcc-${gcc_version}"
     check g++
-    check "g++-${gcc_version}"
-    check cpp
-    check "cpp-${gcc_version}"
     check gcov
 
     echo
@@ -197,9 +163,9 @@ else
     checked=$((checked + 1))
     tmp_clone="$(mktemp -d)"
     if git clone --depth 1 https://github.com/XRPLF/actions.git "${tmp_clone}/actions" >/dev/null 2>&1; then
-        printf '  ✅ git clone over HTTPS\n'
+        printf '  [ ok ] git clone over HTTPS\n'
     else
-        printf '  ❌ git clone over HTTPS\n'
+        printf '  [MISS] git clone over HTTPS\n'
         missing+=("git-https-clone")
     fi
     rm -rf "${tmp_clone}"
@@ -207,9 +173,9 @@ fi
 
 echo
 if [ "${#missing[@]}" -eq 0 ]; then
-    echo "✅ All ${checked} checked tools are present and runnable."
+    echo "All ${checked} checked tools are present and runnable."
 else
-    echo "❌ Missing or non-functional tools (${#missing[@]} of ${checked}):" >&2
+    echo "Missing or non-functional tools (${#missing[@]} of ${checked}):" >&2
     for tool in "${missing[@]}"; do
         echo "  - ${tool}" >&2
     done

cfg/xrpld-example.cfg

@@ -1671,143 +1671,3 @@ validators.txt
 # set to ssl_verify to 0.
 [ssl_verify]
 1
-#-------------------------------------------------------------------------------
-#
-# 11. Telemetry (OpenTelemetry Tracing)
-#
-#-------------------------------------------------------------------------------
-#
-# Enables distributed tracing via OpenTelemetry. This section only has an
-# effect if tracing was compiled in: build with CMake -Dtelemetry=ON (or Conan
-# -o telemetry=True), and build it out with -Dtelemetry=OFF (or
-# -o telemetry=False), which reduces all tracing code to no-ops. The option is
-# currently ON so that CI compiles the telemetry code paths; OFF is the
-# intended default once this feature is merged, so pass the value you want
-# rather than relying on the default.
-#
-# Note that -DXRPL_ENABLE_TELEMETRY=OFF does NOT work: XRPL_ENABLE_TELEMETRY is
-# a compile definition added by the build, not a CMake option, so it disables
-# nothing. CMake only lists it at the end of configuration under
-# "Manually-specified variables were not used by the project".
-#
-# [telemetry]
-#
-# enabled=0
-#
-#   Enable or disable telemetry at runtime. Default: 0 (disabled).
-#
-# service_name=xrpld
-#
-#   OTel resource attribute `service.name`. Default: xrpld.
-#   The node's network ID (from [network_id]) is automatically added
-#   as the `xrpl.network.id` and `xrpl.network.type` resource attributes.
-#
-# service_instance_id=<node_public_key>
-#
-#   OTel resource attribute `service.instance.id`. Uniquely identifies
-#   this node. Default: the node's public key (auto-detected).
-#
-#   SET THIS EXPLICITLY IF YOU USE THE METRICS PIPELINE. The node-public-key
-#   fallback only reaches traces: the metrics resource is built during
-#   startup, before the node key is known, and cannot be changed afterwards.
-#   With this key unset, metrics export with an empty service.instance.id and
-#   the per-node filter on the Grafana dashboards has nothing to split on.
-#
-# endpoint=http://localhost:4318/v1/traces
-#
-#   The OTLP/HTTP exporter endpoint for TRACES. The server sends trace data
-#   as protobuf-encoded HTTP POST requests to this URL.
-#   Default: http://localhost:4318/v1/traces.
-#
-#   beast::insight metrics ([insight] server=otel) follow this setting: a
-#   trailing /v1/traces is rewritten to /v1/metrics.
-#
-# metrics_endpoint=http://localhost:4318/v1/metrics
-#
-#   The OTLP/HTTP exporter endpoint for the internal metrics pipeline
-#   (the XRPL_METRIC_* instruments). This is a separate setting from
-#   `endpoint` and does NOT follow it, so a node exporting to a remote
-#   collector must set both.
-#   Default: http://localhost:4318/v1/metrics.
-#
-# --- TLS settings for the OTLP exporter connection ---
-#
-# use_tls=0
-#
-#   Enable TLS for the OTLP/HTTP exporter connection. Default: 0 (off).
-#
-# tls_ca_cert=
-#
-#   Path to a PEM-encoded CA certificate bundle for TLS verification.
-#   Only used when use_tls=1. Default: empty (system CA store).
-#
-# tls_client_cert=
-#
-#   Path to this node's PEM-encoded client certificate, presented to the
-#   collector for mutual TLS (mTLS). Requires use_tls=1. Leave empty
-#   for one-way (server-only) TLS. Default: empty.
-#
-#   To enable mTLS, both tls_client_cert and tls_client_key must be
-#   specified. If only one is provided, xrpld will fail to start. Providing
-#   them while use_tls=0 also fails to start, rather than being ignored.
-#   Both checks apply only when enabled=1; with telemetry disabled these
-#   settings are read but never validated.
-#
-# tls_client_key=
-#
-#   Path to the PEM-encoded private key for tls_client_cert. Required
-#   whenever tls_client_cert is set. Requires use_tls=1. Both conditions
-#   are enforced exactly as described under tls_client_cert above: when
-#   enabled=1, breaking either one makes xrpld fail to start.
-#   Default: empty.
-#
-#   Head sampling is intentionally fixed at 1.0 (sample everything) and is
-#   not configurable. A per-node sampling ratio would let nodes make
-#   divergent keep/drop decisions for the same distributed trace, producing
-#   broken/partial traces. A ParentBasedSampler ensures spans inheriting a
-#   remote parent honor the upstream decision. Reduce volume at the collector
-#   via tail sampling instead; for node-local post-hoc dropping use
-#   SpanGuard::discard() in code.
-#
-# trace_rpc=1
-#
-#   Enable tracing for JSON-RPC and WebSocket API request handling —
-#   command parsing, execution, and response serialization. Default: 1.
-#
-# trace_transactions=1
-#
-#   Enable tracing for the transaction lifecycle — submission, validation,
-#   application to ledgers, and final disposition. Default: 1.
-#
-# trace_consensus=1
-#
-#   Enable tracing for the consensus round lifecycle — proposals,
-#   validations, mode changes, and ledger acceptance. Default: 1.
-#
-# trace_peer=1
-#
-#   Enable tracing for peer-to-peer protocol messages — overlay message
-#   send/receive, peer handshakes, and routing. High volume; enabled
-#   by default. Default: 1.
-#
-# trace_ledger=1
-#
-#   Enable tracing for ledger close and accept operations — ledger
-#   building, state hashing, and write-back to the node store. Default: 1.
-#
-# --- Batch processor tuning ---
-#
-# batch_size=512
-#
-#   Maximum number of spans exported in a single batch. Default: 512.
-#
-# batch_delay_ms=5000
-#
-#   Maximum delay (milliseconds) before a partial batch is flushed.
-#   Default: 5000 (5 seconds).
-#
-# max_queue_size=2048
-#
-#   Maximum number of spans queued in memory before drops occur.
-#   Default: 2048.
-#

cmake/XrplCompiler.cmake

@@ -266,50 +266,10 @@ elseif(use_lld)
     )
     if("${LD_VERSION}" MATCHES "LLD")
         target_link_libraries(common INTERFACE -fuse-ld=lld)
-        # remembered for the linker flag probe below
-        set(fuse_ld_flag "-fuse-ld=lld")
     endif()
     unset(LD_VERSION)
 endif()
 
-# Linker warnings are errors where we control the toolchain and the dependencies: CI and the Nix dev shell.
-# On non-Nix macOS we suppress the deployment target warning: an old Conan profile may not pin os.version.
-# Only the new Apple linker understands the flag, so probe the actual linker (lld may be selected above).
-if(is_macos OR is_linux)
-    if(is_ci OR is_nix_compiler)
-        if(is_macos)
-            set(fatal_warnings_flag "-Wl,-fatal_warnings")
-        else()
-            set(fatal_warnings_flag "-Wl,--fatal-warnings")
-        endif()
-        message(
-            STATUS
-            "Treating all linker warnings as errors (${fatal_warnings_flag})"
-        )
-        target_link_options(common INTERFACE "${fatal_warnings_flag}")
-        unset(fatal_warnings_flag)
-    elseif(is_macos)
-        set(silence_flag "-Wl,-deployment_target_mismatches,suppress")
-        set(probe_flags ${fuse_ld_flag} "${silence_flag}")
-        include(CheckLinkerFlag)
-        check_linker_flag(
-            CXX
-            "${probe_flags}"
-            have_deployment_target_mismatches
-        )
-        if(have_deployment_target_mismatches)
-            message(
-                STATUS
-                "Silencing macOS deployment target mismatch warnings (${silence_flag})"
-            )
-            target_link_options(common INTERFACE "${silence_flag}")
-        endif()
-        unset(probe_flags)
-        unset(silence_flag)
-    endif()
-endif()
-unset(fuse_ld_flag)
-
 if(assert)
     foreach(var_ CMAKE_C_FLAGS_RELEASE CMAKE_CXX_FLAGS_RELEASE)
         string(REGEX REPLACE "[-/]DNDEBUG" "" ${var_} "${${var_}}")

cmake/XrplCore.cmake

@@ -51,8 +51,6 @@ target_compile_options(
 
 target_link_libraries(xrpl.libpb PUBLIC protobuf::libprotobuf gRPC::grpc++)
 
-add_dependencies(tidy_prerequisites xrpl.libpb)
-
 # TODO: Clean up the number of library targets later.
 add_library(xrpl.imports.main INTERFACE)
 
@@ -80,19 +78,6 @@ include(target_link_modules)
 # Level 01
 add_module(xrpl beast)
 target_link_libraries(xrpl.libxrpl.beast PUBLIC xrpl.imports.main)
-# OTelCollector in beast/insight uses the OTel Metrics SDK when telemetry is
-# enabled. Link the Conan-provided umbrella target rather than individual
-# component targets: the OTel package's per-component dependency graph is
-# under-declared (e.g. the OTLP client references sdk::common symbols without
-# declaring the edge), so naming components directly reorders the static-link
-# line into an unresolvable state. The umbrella carries the full, internally
-# consistent graph the package authors validated.
-if(telemetry)
-    target_link_libraries(
-        xrpl.libxrpl.beast
-        PUBLIC opentelemetry-cpp::opentelemetry-cpp
-    )
-endif()
 
 include(GitInfo)
 add_module(xrpl git)
@@ -219,37 +204,19 @@ target_link_libraries(
         xrpl.libxrpl.conditions
 )
 
-# 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).
-#
-# Declared before its consumers (consensus, tx) because add_module isolates
-# each module's headers: a module can only include xrpl/telemetry/ headers if
-# it links this target, and the target must already exist at that point.
-#
-# Links xrpl.libxrpl.protocol PRIVATELY for sha512Half (digest.h)
-add_module(xrpl telemetry)
+add_module(xrpl tx)
+# The wasm engine is a Rust crate reached over cxx: the bridge target supplies the
+# generated `lib.h` and `rust/cxx.h` that `tx/wasm` compiles against, and the Rust
+# static library everything downstream links. PUBLIC because the include path travels
+# with the module's own public headers.
 target_link_libraries(
-    xrpl.libxrpl.telemetry
-    PUBLIC xrpl.libxrpl.basics xrpl.libxrpl.beast xrpl.libxrpl.config
-    PRIVATE xrpl.libxrpl.protocol
+    xrpl.libxrpl.tx
+    PUBLIC xrpl.libxrpl.ledger xrpl_wasm_vm_ffi_cxxbridge
 )
-if(telemetry)
-    # Telemetry owns both the trace and (as of the direct-metrics API) the
-    # metrics pipeline. Link the umbrella target: it supplies the trace and
-    # metrics SDK components with the correct static-link ordering, which
-    # naming components individually does not (the package under-declares
-    # inter-component dependencies).
-    target_link_libraries(
-        xrpl.libxrpl.telemetry
-        PUBLIC opentelemetry-cpp::opentelemetry-cpp
-    )
-endif()
+# Those headers do not exist at configure time, and the header-verification target
+# compiles this module's headers on their own, so both need the crates built first.
+add_dependencies(xrpl.libxrpl.tx xrpl_crates)
 
-# Links xrpl.libxrpl.telemetry for the consensus tracing spans declared in
-# include/xrpl/consensus/ConsensusSpanNames.h.
 add_module(xrpl consensus)
 target_link_libraries(
     xrpl.libxrpl.consensus
@@ -258,13 +225,6 @@ target_link_libraries(
         xrpl.libxrpl.json
         xrpl.libxrpl.protocol
         xrpl.libxrpl.ledger
-        xrpl.libxrpl.telemetry
-)
-
-add_module(xrpl tx)
-target_link_libraries(
-    xrpl.libxrpl.tx
-    PUBLIC xrpl.libxrpl.ledger xrpl.libxrpl.telemetry
 )
 
 add_library(xrpl.libxrpl)
@@ -301,7 +261,6 @@ target_link_modules(
     resource
     server
     shamap
-    telemetry
     tx
 )
 

cmake/XrplCov.cmake

@@ -44,7 +44,6 @@ setup_target_for_coverage_gcovr(
     EXCLUDE
         "src/test"
         "src/tests"
-        "src/benchmarks"
         "include/xrpl/beast/test"
         "include/xrpl/beast/unit_test"
         "${CMAKE_BINARY_DIR}/pb-xrpl.libpb"

cmake/XrplDocs.cmake

@@ -27,12 +27,8 @@ file(
     src/*.cpp
     src/*.md
     Builds/*.md
+    *.md
 )
-# Add only top-level .md files (README, CONTRIBUTING, etc.) without
-# recursing into dot-directories like .claude/ whose files are not
-# valid Doxygen/CMake sources.
-file(GLOB doxygen_top_md CONFIGURE_DEPENDS "*.md")
-list(APPEND doxygen_input ${doxygen_top_md})
 list(APPEND doxygen_input external/README.md)
 set(dependencies "${doxygen_input}" "${doxyfile}")
 

cmake/XrplSettings.cmake

@@ -32,11 +32,6 @@ endif()
 
 option(benchmark "Build benchmarks" ON)
 
-# When OFF, the crates directory is not added to the build at all: no Rust
-# toolchain is required, no cxxbridge bindings are generated, and the C++ tests
-# that consume those bindings are left out of the build tree.
-option(rust "Build the Rust crates and the C++ code that depends on them" OFF)
-
 # Enabled by default so every header is compiled on its own as the main file of
 # its own compile_commands.json entry - this is what lets clang-tidy (and clangd
 # and IDEs) analyse a header's own includes directly. The per-header objects are

conan.lock

@@ -10,23 +10,19 @@
         "rocksdb/10.5.1#4a197eca381a3e5ae8adf8cffa5aacd0%1782392413.075713",
         "re2/20251105#8579cfd0bda4daf0683f9e3898f964b4%1782392402.431897",
         "protobuf/6.33.5#ff253ead763bd8d9904a52979cd21e81%1782392410.233933",
-        "opentelemetry-cpp/1.28.0#2cbf71db4e0e0535df20be305005cb2f%1785939947.292581",
         "openssl/3.6.3#f806de8933e3bf6f01016c6a888cee2e%1783945160.863288",
         "nudb/2.0.9#11149c73f8f2baff9a0198fe25971fc7%1782392402.297166",
-        "nlohmann_json/3.11.3#45828be26eb619a2e04ca517bb7b828d%1701220705.259",
         "mpt-crypto/1.0.2#b313cef0c1a493eb970ad185b2e9bab7%1784285108.866483",
         "lz4/1.10.0#982d9b673900f665a1da109e09c17cab%1782392402.164188",
         "libiconv/1.17#9923bc6dc6f106646d6967e0039a5ada%1782392792.775744",
-        "libcurl/8.21.0#8c26e59c04891ba3373ea3552e18f67f%1783067699.863",
         "libbacktrace/cci.20210118#a7691bfccd8caaf66309df196790a5a1%1782392402.420732",
         "libarchive/3.8.7#c446109bd1f1d8ba7936c94189bc50e6%1782392403.066892",
         "jemalloc/5.3.1#1fc58d55316041f10fbc1e8a2eae632a%1776700028.228",
         "gtest/1.17.0#5224b3b3ff3b4ce1133cbdd27d53ee7d%1782392402.791979",
         "grpc/1.81.1#f729f6d75992d20f9c72828e9142d62f%1783945160.094135",
-        "fast_float/8.2.10#f6f28d6bb22112078e7dbda611caf681%1785888854.601666",
+        "fast_float/8.2.10#f6f28d6bb22112078e7dbda611caf681%1782494504.298",
         "ed25519/2015.03#ae761bdc52730a843f0809bdf6c1b1f6%1782307148.15562",
         "date/3.0.4#862e11e80030356b53c2c38599ceb32b%1782392402.538492",
-        "corrosion/0.6.1#bfa292df0a957bc70a450ff316cd9435%1786119416.131296",
         "c-ares/1.34.6#545240bb1c40e2cacd4362d6b8967650%1782392402.681654",
         "bzip2/1.0.8#c470882369c2d95c5c77e970c0c7e321%1782392402.296732",
         "boost/1.91.0#ea540ca2133d831b560036aa24dece3c%1782392419.475605",
@@ -37,15 +33,9 @@
         "zlib/1.3.2#1cb806da49011867778ffb6ac7190fcb%1782392402.122708",
         "strawberryperl/5.32.1.1#8d114504d172cfea8ea1662d09b6333e%1782395692.540639",
         "protobuf/6.33.5#ff253ead763bd8d9904a52979cd21e81%1782392410.233933",
-        "pkgconf/2.5.1#93c2051284cba1279494a43a4fcfeae2%1757684701.089",
-        "opentelemetry-proto/1.7.0#ed6d5bd761bef0afb0ba09676420b9ea%1749461220.268",
-        "ninja/1.13.2#c8c5dc2a52ed6e4e42a66d75b4717ceb%1764096931.974",
         "nasm/2.16.01#31e26f2ee3c4346ecd347911bd126904%1782395690.33162",
         "msys2/cci.latest#d22fe7b2808f5fd34d0a7923ace9c54f%1770657326.649",
-        "meson/1.10.2#9d2d10681fe7fe61c788c58626c89b25%1775558003.754",
         "m4/1.4.19#1727f439cf74e83826ec96d0b4904eee%1784541921.659",
-        "libtool/2.4.7#14e7739cc128bc1623d2ed318008e47e%1755679003.847",
-        "gnu-config/cci.20210814#466e9d4d7779e1c142443f7ea44b4284%1762363589.329",
         "cmake/4.3.3#840cf00ea09777e05c2050a50a82c722%1782392418.696091",
         "b2/5.4.2#ffd6084a119587e70f11cd45d1a386e2%1782392402.624226",
         "automake/1.16.5#b91b7c384c3deaa9d535be02da14d04f%1755524470.56",
@@ -71,9 +61,6 @@
         ],
         "lz4/[>=1.9.4 <2]": [
             "lz4/1.10.0#982d9b673900f665a1da109e09c17cab"
-        ],
-        "protobuf/[>=4.25.3 <7]": [
-            "protobuf/6.33.5#ff253ead763bd8d9904a52979cd21e81"
         ]
     },
     "config_requires": []

conan/init.sh

@@ -1,21 +0,0 @@
-#!/usr/bin/env bash
-# Install our Conan configuration, profiles and the xrplf remote into CONAN_HOME.
-# Safe to re-run; never deletes the Conan home.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
-CONAN_DIR="$(conan config home)"
-
-echo "Installing Conan configuration into ${CONAN_DIR}"
-conan config install "${SCRIPT_DIR}/global.conf"
-conan config install "${SCRIPT_DIR}/profiles" -tf "${CONAN_DIR}/profiles"
-# This script manages these files, so make them read-only - Conan does not
-# preserve the source mode. Only the files: the directories must stay writable
-# for `conan config install` to replace them.
-chmod a-w "${CONAN_DIR}/global.conf"
-find "${CONAN_DIR}/profiles" -type f -exec chmod a-w {} +
-
-echo "Adding the xrplf Conan remote"
-# --index 0: our patched recipes must win over Conan Center.
-conan remote add --index 0 --force xrplf https://conan.xrplf.org/repository/conan/

conan/profiles/default

@@ -1,7 +1,10 @@
 {% set os = detect_api.detect_os() %}
 {% set arch = detect_api.detect_arch() %}
 {% set compiler, version, compiler_exe = detect_api.detect_default_compiler() %}
+{% set compiler_version = version %}
+{% if os == "Linux" %}
 {% set compiler_version = detect_api.default_compiler_version(compiler, version) %}
+{% endif %}
 {% if os == "Macos" %}
 {# Minimum macOS the dependencies target. #}
 {# Without this, Conan builds each dependency against the (possibly newer) host SDK, so the #}
@@ -58,18 +61,3 @@ tools.info.package_id:confs+=["user.package:cppstd_version"]
 {# Scoped to boost/* since it is the only gap. #}
 boost/*:MACOSX_DEPLOYMENT_TARGET={{ min_macos_version }}
 {% endif %}
-{% if compiler == "gcc" and compiler_version < 13 %}
-tools.build:cxxflags+=['-Wno-restrict']
-{% endif %}
-{% if os == "Windows" %}
-# opentelemetry-cpp's recipe removes the `shared` option on Windows and never
-# sets BUILD_SHARED_LIBS, so its upstream CMake defaults the protobuf-generated
-# `opentelemetry_proto` target to a DLL (opentelemetry_proto.dll). The rest of
-# the project links statically and nothing deploys that DLL next to the
-# executables, so the telemetry unit test fails to start with
-# STATUS_DLL_NOT_FOUND (0xC0000135). Force the dependency to build fully static
-# so no runtime DLL is produced. The conf is folded into the package id so a
-# fresh static binary is built instead of reusing a previously cached one.
-opentelemetry-cpp/*:tools.cmake.cmaketoolchain:extra_variables={"BUILD_SHARED_LIBS": "OFF"}
-opentelemetry-cpp/*:tools.info.package_id:confs+=["tools.cmake.cmaketoolchain:extra_variables"]
-{% endif %}

conanfile.py

@@ -22,14 +22,12 @@ class Xrpl(ConanFile):
         "rocksdb": [True, False],
         "shared": [True, False],
         "static": [True, False],
-        "telemetry": [True, False],
         "tests": [True, False],
         "unity": [True, False],
         "xrpld": [True, False],
     }
 
     requires = [
-        "corrosion/0.6.1",
         "ed25519/2015.03",
         "fast_float/8.2.10",
         "grpc/1.81.1",
@@ -57,7 +55,6 @@ class Xrpl(ConanFile):
         "rocksdb": True,
         "shared": False,
         "static": True,
-        "telemetry": True,
         "tests": False,
         "unity": False,
         "xrpld": False,
@@ -148,10 +145,6 @@ class Xrpl(ConanFile):
             self.requires("rocksdb/10.5.1")
         self.requires("secp256k1/0.7.1", transitive_headers=True)
         self.requires("sqlite3/3.53.0", force=True)
-        # OpenTelemetry C++ SDK for distributed tracing (optional).
-        # Provides OTLP/HTTP exporter, batch span processor, and trace API.
-        if self.options.telemetry:
-            self.requires("opentelemetry-cpp/1.28.0")
         self.requires("xxhash/0.8.3", transitive_headers=True)
 
     exports_sources = (
@@ -181,7 +174,6 @@ class Xrpl(ConanFile):
         tc.variables["rocksdb"] = self.options.rocksdb
         tc.variables["BUILD_SHARED_LIBS"] = self.options.shared
         tc.variables["static"] = self.options.static
-        tc.variables["telemetry"] = self.options.telemetry
         tc.variables["unity"] = self.options.unity
         tc.variables["xrpld"] = self.options.xrpld
         tc.generate()
@@ -236,5 +228,3 @@ class Xrpl(ConanFile):
         ]
         if self.options.rocksdb:
             libxrpl.requires.append("rocksdb::librocksdb")
-        if self.options.telemetry:
-            libxrpl.requires.append("opentelemetry-cpp::opentelemetry-cpp")

crates/.cargo/config.toml

@@ -1,17 +1,5 @@
-# The Rust static libraries are linked into C++ targets, so the runtime linkage
-# here has to match what the C++ build uses (see cmake/XrplCompiler.cmake).
-#
-# macOS needs nothing: AppleClang cannot link libgcc/libc++ statically, so the
-# C++ build skips those flags on Apple as well.
-
-# Both amd64 and arm64 Linux builds link libgcc statically. This only affects
-# links that rustc itself drives (`cargo test` binaries and the like) — the
-# `staticlib` crates consumed by CMake are archived, not linked, so rustc
-# silently ignores link args for them. Keeping libgcc_s.so.1 off the xrpld link
-# line is handled in crates/CMakeLists.txt instead.
-[target.'cfg(target_os = "linux")']
+[target.x86_64-unknown-linux-gnu]
 rustflags = ["-C", "link-args=-static-libgcc"]
 
-# Windows builds use the static MSVC runtime.
-[target.'cfg(windows)']
+[target.x86_64-pc-windows-msvc]
 rustflags = ["-C", "target-feature=+crt-static"]

crates/CMakeLists.txt

@@ -1,90 +1,37 @@
-find_package(Corrosion REQUIRED)
+set(CORROSION_VERSION 0.6.1)
+
+find_package(Corrosion ${CORROSION_VERSION} QUIET)
+if(NOT Corrosion_FOUND)
+    include(FetchContent)
+    FetchContent_Declare(
+        Corrosion
+        GIT_REPOSITORY https://github.com/corrosion-rs/corrosion.git
+        GIT_TAG v${CORROSION_VERSION}
+    )
+    FetchContent_MakeAvailable(Corrosion)
+endif()
 
 corrosion_import_crate(MANIFEST_PATH ${CMAKE_CURRENT_SOURCE_DIR}/Cargo.toml)
 
-# The generated C++ lands in the build tree, so put a .clang-tidy next to it to
-# keep clang-tidy from analyzing code we don't own.
-configure_file(
-    generated.clang-tidy
-    "${CMAKE_CURRENT_BINARY_DIR}/.clang-tidy"
-    COPYONLY
+file(
+    WRITE "${CMAKE_CURRENT_BINARY_DIR}/.clang-tidy"
+    "# Auto-generated by crates/CMakeLists.txt. Do not edit.\n"
+    "# Neutralizes clang-tidy for corrosion/cxxbridge-generated C++.\n"
+    "# One check kept enabled to avoid clang-tidy's \"no checks enabled\" error.\n"
+    "Checks: '-*,google-readability-todo'\n"
+    "WarningsAsErrors: ''\n"
+    "HeaderFilterRegex: ''\n"
+    "InheritParentConfig: false\n"
 )
 
+# Umbrella target that aggregates all crate-generated code (cxxbridge headers,
+# etc.). Build this before running clang-tidy so generated headers are present.
 add_custom_target(xrpl_crates)
-add_dependencies(tidy_prerequisites xrpl_crates)
-
-# On macOS, ld warns `ignoring duplicate libraries` when linking a crate.
-# Corrosion is the source of both duplicates it names:
-#
-# * The crate archive and its cxxbridge archive, because
-#   `corrosion_add_cxxbridge` makes the two depend on each other, and CMake
-#   repeats a static library cycle on the link line so single-pass linkers can
-#   resolve it. (LINK_INTERFACE_MULTIPLICITY can only raise that count.)
-# * `-lSystem`, which Corrosion copies from rustc's `native-static-libs` even
-#   though the compiler driver always links libSystem.
-#
-# ld needs neither: it resolves the cycle from one copy of each archive and
-# links libSystem once. So silence the warning rather than rewrite Corrosion's
-# link interface, which the cycle is also part of. The option itself is old —
-# Xcode 15 is only where the warning became the default — and the check below
-# leaves it out on a linker that does not know it.
-if(is_macos)
-    include(CheckLinkerFlag)
-    check_linker_flag(
-        CXX
-        -Wl,-no_warn_duplicate_libraries
-        have_no_warn_duplicate_libraries
-    )
-endif()
-
-function(_unlink_libgcc_s crate)
-    if(NOT (is_linux AND static))
-        return()
-    endif()
-
-    # Corrosion exposes a crate's staticlib as an imported `<crate>-static`
-    # target and puts the native libs in its INTERFACE_LINK_LIBRARIES. If either
-    # of those changes, warn instead of silently letting libgcc_s.so.1 return.
-    set(imported "${crate}-static")
-    if(NOT TARGET ${imported})
-        message(
-            FATAL_ERROR
-            "Corrosion did not create the imported target '${imported}', so "
-            "libgcc_s cannot be removed from the link interface of '${crate}'. "
-            "xrpld will link libgcc_s.so.1 dynamically. Check where Corrosion "
-            "${CORROSION_VERSION} now records `native-static-libs`."
-        )
-        return()
-    endif()
-
-    get_target_property(libs ${imported} INTERFACE_LINK_LIBRARIES)
-    if(NOT "gcc_s" IN_LIST libs)
-        message(
-            WARNING
-            "'gcc_s' was not in the link interface of '${imported}' as "
-            "expected. If the Rust toolchain stopped reporting it this "
-            "workaround is obsolete and can be deleted; otherwise xrpld may "
-            "link libgcc_s.so.1 dynamically. Verify with: "
-            "objdump -p xrpld | grep NEEDED"
-        )
-        return()
-    endif()
-
-    list(REMOVE_ITEM libs gcc_s)
-    set_property(TARGET ${imported} PROPERTY INTERFACE_LINK_LIBRARIES ${libs})
-endfunction()
 
+# add_xrpl_crate(<name> CRATE <crate> FILES <file>...) Creates a cxxbridge
+# target <name>_cxxbridge and registers it with xrpl_crates.
 function(add_xrpl_crate name)
     cmake_parse_arguments(ARG "" "CRATE" "FILES" ${ARGN})
-    _unlink_libgcc_s(${ARG_CRATE})
-    # `cc` picks its runtime flag from `crt-static` alone, so it compiles a
-    # crate's C++ with `-MT`; Debug needs `-MTd` (to match cmake/XrplCompiler.cmake).
-    if(is_msvc)
-        corrosion_set_env_vars(
-            ${ARG_CRATE}
-            "$<$<CONFIG:Debug>:CXXFLAGS=-MTd>"
-        )
-    endif()
     corrosion_add_cxxbridge(${name}_cxxbridge CRATE ${ARG_CRATE} FILES
                             ${ARG_FILES}
     )
@@ -92,13 +39,21 @@ function(add_xrpl_crate name)
     # validates INTERFACE_SOURCES on consuming targets. Clear it to skip the
     # existence check — build-time ordering is enforced by the custom commands.
     set_target_properties(${name}_cxxbridge PROPERTIES INTERFACE_SOURCES "")
-    if(have_no_warn_duplicate_libraries)
-        target_link_options(
-            ${name}_cxxbridge
-            INTERFACE -Wl,-no_warn_duplicate_libraries
-        )
-    endif()
     add_dependencies(xrpl_crates ${name}_cxxbridge)
 endfunction()
 
-add_xrpl_crate(rs_hello_world CRATE rs_hello_world FILES lib.rs)
+add_xrpl_crate(xrpl_wasm_vm_ffi CRATE xrpl_wasm_vm_ffi FILES lib.rs)
+
+# Test-only, and deliberately not part of xrpl_wasm_vm_ffi: it carries the `wat` assembler,
+# which the engine's `wasmi default-features = false` exists to keep out of the consensus
+# path. Linked from src/tests/libxrpl only, so the shipped node cannot contain it.
+add_xrpl_crate(xrpl_wasm_testkit CRATE xrpl_wasm_testkit FILES lib.rs)
+
+# The wasm bridge `include!`s a project header, so its generated translation unit needs
+# the project's include root. Deliberately only that: a header reached from here must
+# stay light enough to compile without the Boost paths this target does not get, which
+# is why `HostContext.h` forward-declares `xrpl::HostFunctions` instead of including it.
+target_include_directories(
+    xrpl_wasm_vm_ffi_cxxbridge
+    PRIVATE ${CMAKE_SOURCE_DIR}/include
+)

crates/Cargo.lock

@@ -8,6 +8,18 @@ version = "1.0.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
 
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+
 [[package]]
 name = "cc"
 version = "1.2.61"
@@ -66,7 +78,7 @@ dependencies = [
  "cxxbridge-cmd",
  "cxxbridge-flags",
  "cxxbridge-macro",
- "foldhash",
+ "foldhash 0.2.0",
  "link-cplusplus",
 ]
 
@@ -129,12 +141,27 @@ version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
 
+[[package]]
+name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+
 [[package]]
 name = "foldhash"
 version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
 
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "foldhash 0.1.5",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.17.0"
@@ -148,9 +175,21 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
  "equivalent",
- "hashbrown",
+ "hashbrown 0.17.0",
 ]
 
+[[package]]
+name = "leb128fmt"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
+
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
 [[package]]
 name = "link-cplusplus"
 version = "1.0.12"
@@ -160,6 +199,12 @@ dependencies = [
  "cc",
 ]
 
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.106"
@@ -178,19 +223,18 @@ dependencies = [
  "proc-macro2",
 ]
 
-[[package]]
-name = "rs-hello_world"
-version = "0.1.0"
-dependencies = [
- "cxx",
-]
-
 [[package]]
 name = "scratch"
 version = "1.0.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d68f2ec51b097e4c1a75b681a8bec621909b5e91f15bb7b840c4f2f7b01148b2"
 
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
 [[package]]
 name = "serde"
 version = "1.0.228"
@@ -227,6 +271,22 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
 
+[[package]]
+name = "spin"
+version = "0.9.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3763264f6b73151db08c50ff20d7d8a0b8796e021cdea7ceedad07b80155fa0e"
+
+[[package]]
+name = "string-interner"
+version = "0.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23de088478b31c349c9ba67816fa55d9355232d63c3afea8bf513e31f0f1d2c0"
+dependencies = [
+ "hashbrown 0.15.5",
+ "serde",
+]
+
 [[package]]
 name = "strsim"
 version = "0.11.1"
@@ -276,6 +336,99 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
 
+[[package]]
+name = "wasm-encoder"
+version = "0.254.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09480d646178e5fdd12bb06e812d0af9a3a191dbc9cd697fdc86687beade7393"
+dependencies = [
+ "leb128fmt",
+ "wasmparser 0.254.0",
+]
+
+[[package]]
+name = "wasmi"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2300d0f78cba12f14e29e8dd157ea64050c0a688179aefdb2050105805594a0c"
+dependencies = [
+ "spin",
+ "wasmi_collections",
+ "wasmi_core",
+ "wasmi_ir",
+ "wasmparser 0.239.0",
+]
+
+[[package]]
+name = "wasmi_collections"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8a8c42a2a76148d43097b1d7cc2a5bf33d5c23bd4dd69015fc887e311767884"
+dependencies = [
+ "string-interner",
+]
+
+[[package]]
+name = "wasmi_core"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9013136083d988725953390bf668b64b7a218fabf26f8b913bbc59546b97ee27"
+dependencies = [
+ "libm",
+]
+
+[[package]]
+name = "wasmi_ir"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba1fa003f79156f406d62ef0e1464dc03e11ace37170e9fa7524299a75ad8f68"
+dependencies = [
+ "wasmi_core",
+]
+
+[[package]]
+name = "wasmparser"
+version = "0.239.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8c9d90bb93e764f6beabf1d02028c70a2156a6583e63ac4218dd07ef733368b0"
+dependencies = [
+ "bitflags",
+ "indexmap",
+]
+
+[[package]]
+name = "wasmparser"
+version = "0.254.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d5769a29f799fbab136aaf65b4fe5384cd7d93fe6fc9ba0dcb6c8382a1f16e27"
+dependencies = [
+ "bitflags",
+ "indexmap",
+ "semver",
+]
+
+[[package]]
+name = "wast"
+version = "254.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7ed4dfc8f6b9fc38b231065e2cdfbf7359af5ab945990abf09658dcc63c3e32"
+dependencies = [
+ "bumpalo",
+ "leb128fmt",
+ "memchr",
+ "unicode-width",
+ "wasm-encoder",
+]
+
+[[package]]
+name = "wat"
+version = "1.254.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7127f7f9b8f127c879991cecd35f494e4628bae1b0874c681414d8d8831e952c"
+dependencies = [
+ "wast",
+]
+
 [[package]]
 name = "winapi-util"
 version = "0.1.11"
@@ -299,3 +452,46 @@ checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
 dependencies = [
  "windows-link",
 ]
+
+[[package]]
+name = "xrpl-host-functions"
+version = "0.1.0"
+dependencies = [
+ "xrpl-host-functions-macros",
+]
+
+[[package]]
+name = "xrpl-host-functions-macros"
+version = "0.1.0"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+ "xrpl-host-functions",
+]
+
+[[package]]
+name = "xrpl-wasm-testkit"
+version = "0.1.0"
+dependencies = [
+ "cxx",
+ "wat",
+]
+
+[[package]]
+name = "xrpl-wasm-vm"
+version = "0.1.0"
+dependencies = [
+ "wasmi",
+ "wat",
+ "xrpl-host-functions",
+]
+
+[[package]]
+name = "xrpl-wasm-vm-ffi"
+version = "0.1.0"
+dependencies = [
+ "cxx",
+ "xrpl-host-functions",
+ "xrpl-wasm-vm",
+]

crates/Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["hello_world"]
+members = ["xrpl-wasm-vm-ffi", "xrpl-wasm-vm", "xrpl-wasm-testkit", "xrpl-host-functions", "xrpl-host-functions-macros"]
 resolver = "3"
 
 [workspace.dependencies]

crates/generated.clang-tidy

@@ -1,10 +0,0 @@
----
-# Neutralizes clang-tidy for the corrosion/cxxbridge-generated C++. Copied into
-# the crates build directory by crates/CMakeLists.txt, next to the generated
-# sources, so clang-tidy picks it up instead of the top-level configuration.
-#
-# One check is kept enabled to avoid clang-tidy's "no checks enabled" error.
-Checks: "-*,google-readability-todo"
-WarningsAsErrors: ""
-HeaderFilterRegex: ""
-InheritParentConfig: false

crates/hello_world/src/lib.rs

@@ -1,10 +0,0 @@
-#[cxx::bridge(namespace = "rs::hello_world")]
-mod ffi {
-    extern "Rust" {
-        fn hello_world() -> String;
-    }
-}
-
-pub fn hello_world() -> String {
-    "hello_world".to_string()
-}

crates/xrpl-host-functions-macros/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "xrpl-host-functions-macros"
+version = "0.1.0"
+edition.workspace = true
+
+[lib]
+proc-macro = true
+
+[dependencies]
+syn = { version = "3", features = ["full"] }
+quote = "1"
+proc-macro2 = "1"
+
+# The expansion names `::xrpl_host_functions::HostFnSpec`, so the doctest needs the
+# facade crate. Cargo allows this cycle because dev-dependencies are outside the
+# library build graph.
+[dev-dependencies]
+xrpl-host-functions.path = "../xrpl-host-functions"

crates/xrpl-host-functions-macros/src/errors.rs

@@ -0,0 +1,12 @@
+/// Folds accumulated diagnostics into the single error a macro can return.
+///
+/// `syn::Error` is itself a collection: `combine` appends, and
+/// `into_compile_error` emits one `compile_error!` per recorded span. Folding
+/// instead of returning the first error means every mistake in a
+/// `host_functions!` block surfaces in one build rather than one per rebuild.
+pub(crate) fn combine(errors: Vec<syn::Error>) -> Option<syn::Error> {
+    errors.into_iter().reduce(|mut first, next| {
+        first.combine(next);
+        first
+    })
+}

crates/xrpl-host-functions-macros/src/lib.rs

@@ -0,0 +1,384 @@
+mod errors;
+mod parsed_host_function;
+
+use std::collections::HashSet;
+
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::{
+    TraitItemFn,
+    parse::{Parse, ParseStream},
+    parse2,
+};
+
+use parsed_host_function::ParsedHostFunction;
+
+/// Declares the wasm host ABI once, and generates everything that follows from it.
+///
+/// The input is a block of `fn` declarations, each carrying the gas cost the host
+/// charges before the call and the name the guest imports it under. Doc comments
+/// are kept and appear on the generated items.
+///
+/// This crate is an implementation detail of `xrpl-host-functions`, which
+/// hand-writes the types the expansion refers to and holds the one declaration
+/// block. The expansion names those types by absolute path, so a call site needs
+/// `xrpl-host-functions` as a dependency but no imports from it.
+///
+/// ```
+/// use xrpl_host_functions::HostResult;
+/// use xrpl_host_functions_macros::host_functions;
+///
+/// host_functions! {
+///     /// The sequence number of the ledger being built, as 4 little-endian bytes.
+///     #[gas = 60]
+///     #[wasm_name = "ldgr_index"]
+///     fn get_ledger_sqn(&self, out: &mut [u8]) -> HostResult<usize>;
+///
+///     /// Writes `msg` to the trace log.
+///     #[gas = 500]
+///     #[wasm_name = "trace_num"]
+///     fn trace_num(&self, msg: &str, number: i64) -> HostResult<()>;
+/// }
+///
+/// // A `HostFunctions` trait, holding the declarations verbatim:
+/// struct Host;
+/// impl HostFunctions for Host {
+///     fn get_ledger_sqn(&self, out: &mut [u8]) -> HostResult<usize> {
+///         out[..4].copy_from_slice(&7u32.to_le_bytes());
+///         Ok(4)
+///     }
+///     fn trace_num(&self, _msg: &str, _number: i64) -> HostResult<()> { Ok(()) }
+/// }
+///
+/// // A `HostFunctionSpec` enum carrying the ABI metadata as a `const` table:
+/// assert_eq!(HostFunctionSpec::GetLedgerSqn.gas(), 60);
+/// assert_eq!(HostFunctionSpec::TraceNum.wasm_name(), "trace_num");
+/// assert_eq!(HostFunctionSpec::ALL.len(), 2);
+/// ```
+///
+/// A declaration must be a plain `fn` taking `&self` and returning
+/// `HostResult<T>`, with no body and no generics: it maps to exactly one wasm
+/// import signature. Two declarations may not share a `wasm_name`, nor collapse to
+/// the same PascalCase variant.
+#[proc_macro]
+pub fn host_functions(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
+    expand(input.into())
+        .unwrap_or_else(syn::Error::into_compile_error)
+        .into()
+}
+
+fn expand(input: TokenStream) -> syn::Result<TokenStream> {
+    let HostFunctionsInput { functions } = parse2(input)?;
+
+    let mut parsed = Vec::with_capacity(functions.len());
+    let mut errors = Vec::new();
+    for function in functions {
+        match ParsedHostFunction::parse(function) {
+            Ok(function) => parsed.push(function),
+            Err(error) => errors.push(error),
+        }
+    }
+    if let Some(error) = errors::combine(errors) {
+        return Err(error);
+    }
+    if let Some(error) = errors::combine(collisions(&parsed)) {
+        return Err(error);
+    }
+
+    Ok(generate(&parsed))
+}
+
+/// Names two declarations may not share, because the generated code would then
+/// fail to compile at a span the caller cannot see.
+fn collisions(functions: &[ParsedHostFunction]) -> Vec<syn::Error> {
+    let mut errors = Vec::new();
+    let mut variants = HashSet::new();
+    let mut wasm_names = HashSet::new();
+
+    for function in functions {
+        if !variants.insert(function.variant.to_string()) {
+            errors.push(syn::Error::new_spanned(
+                &function.variant,
+                format!(
+                    "another host function already becomes the `{}` variant",
+                    function.variant
+                ),
+            ));
+        }
+        if !wasm_names.insert(function.wasm_name.value()) {
+            errors.push(syn::Error::new_spanned(
+                &function.wasm_name,
+                format!(
+                    "another host function is already imported as `{}`",
+                    function.wasm_name.value()
+                ),
+            ));
+        }
+    }
+
+    errors
+}
+
+fn generate(functions: &[ParsedHostFunction]) -> TokenStream {
+    let trait_methods = functions.iter().map(ParsedHostFunction::trait_method);
+    let variants = functions
+        .iter()
+        .map(ParsedHostFunction::variant_declaration);
+    let spec_arms = functions.iter().map(ParsedHostFunction::spec_arm);
+    let all = functions.iter().map(|function| &function.variant);
+
+    quote! {
+        /// The host side of the wasm ABI: one method per function a guest may
+        /// import.
+        ///
+        /// Implement it once per execution environment — the ledger host, a test
+        /// double, a benchmark fake — and a guest module cannot tell them apart.
+        /// Each method is one declaration from the `host_functions!` block, as
+        /// written; its `&self` receiver is not part of the ABI the guest sees,
+        /// so a host that must mutate does so behind interior mutability.
+        ///
+        /// # The output contract
+        ///
+        /// A method handed an `out` buffer **writes into it only when the whole
+        /// value fits, and returns the value's true length whether it fitted or
+        /// not.**
+        ///
+        /// The length is the value's, not the number of bytes written, because it
+        /// is how a guest that asked with too small a buffer learns the size to
+        /// ask for next time. The engine turns a length past the buffer into
+        /// `BufferTooSmall`, and one past the field cap into `DataFieldTooLarge`,
+        /// so a host needs to know neither.
+        ///
+        /// Writing nothing unless the value fits is the half only a host can hold
+        /// up. An engine can bound how many bytes are *writable* — and does, by
+        /// handing over a region clamped to the field cap — but it cannot take
+        /// back what a method already put there. A host that wrote a truncated
+        /// prefix and then reported the larger length would leave those bytes in
+        /// guest memory behind a refusal the guest is told to ignore. C++'s
+        /// `setData` is the reference point: it wrote only on a value that fit.
+        pub trait HostFunctions {
+            #(#trait_methods)*
+        }
+
+        /// One row of the ABI table: what [`HostFunctionSpec::wasm_name`] and
+        /// [`HostFunctionSpec::gas`] read from.
+        ///
+        /// Private, and the only reason it exists is to keep both of them fed
+        /// from a single `match` over the declarations.
+        struct HostFnSpec {
+            name: &'static str,
+            gas: u64,
+        }
+
+        /// Identifies one host function, and is the compile-time source of its
+        /// ABI metadata.
+        ///
+        /// One variant per `host_functions!` declaration, named by converting the
+        /// function name to PascalCase. [`Self::ALL`] is the whole ABI, which is
+        /// what a wasm engine iterates to build its import table.
+        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+        pub enum HostFunctionSpec {
+            #(#variants,)*
+        }
+
+        impl HostFunctionSpec {
+            /// Every host function, in the order declared.
+            ///
+            /// This is the complete import surface a guest may link against: a
+            /// function absent here cannot be called, and one present here must
+            /// be registered for a module that imports it to instantiate.
+            pub const ALL: &'static [Self] = &[#(Self::#all,)*];
+
+            /// This function's row of the ABI table.
+            const fn spec(self) -> HostFnSpec {
+                match self {
+                    #(#spec_arms,)*
+                }
+            }
+
+            /// The name a guest imports this function under.
+            ///
+            /// A guest's import name must match this exactly, or the module
+            /// fails to instantiate. Usable in `const` context, so import lists
+            /// can be built at compile time.
+            pub const fn wasm_name(self) -> &'static str {
+                self.spec().name
+            }
+
+            /// Gas charged before the call runs, independent of its arguments.
+            ///
+            /// Consensus-relevant: two nodes that disagree on this value
+            /// disagree on transaction outcomes. Usable in `const` context, so
+            /// gas tables can be built at compile time.
+            pub const fn gas(self) -> u64 {
+                self.spec().gas
+            }
+        }
+    }
+}
+
+struct HostFunctionsInput {
+    functions: Vec<TraitItemFn>,
+}
+
+impl Parse for HostFunctionsInput {
+    fn parse(input: ParseStream) -> syn::Result<Self> {
+        let mut functions = Vec::new();
+        while !input.is_empty() {
+            functions.push(input.parse()?);
+        }
+        Ok(HostFunctionsInput { functions })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn accepts_an_empty_block() {
+        expand(quote! {}).unwrap();
+    }
+
+    #[test]
+    fn reports_mistakes_from_every_function() {
+        let error = expand(quote! {
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+
+            #[gas = 2000]
+            fn sha512_half(&self, data: &[u8]) -> HostResult<[u8; 32]>;
+        })
+        .expect_err("expected parsing to fail");
+
+        let messages: Vec<_> = error.into_iter().map(|error| error.to_string()).collect();
+        assert_eq!(messages.len(), 2, "{messages:?}");
+        assert!(messages[0].contains("missing `#[gas"), "{messages:?}");
+        assert!(messages[1].contains("missing `#[wasm_name"), "{messages:?}");
+    }
+
+    #[test]
+    fn propagates_syntax_errors() {
+        let error = expand(quote! { fn missing_semicolon() }).expect_err("expected a syntax error");
+        assert!(!error.to_string().is_empty());
+    }
+
+    /// The messages of every diagnostic recorded by one failed `expand`.
+    fn messages(input: TokenStream) -> Vec<String> {
+        let Err(error) = expand(input) else {
+            panic!("expected expansion to fail");
+        };
+        error.into_iter().map(|error| error.to_string()).collect()
+    }
+
+    #[test]
+    fn generates_the_trait_the_enum_and_the_table() {
+        let generated = expand(quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+
+            #[gas = 500]
+            #[wasm_name = "trace_num"]
+            fn trace_num(&self, msg: &str, number: i64) -> HostResult<()>;
+        })
+        .unwrap()
+        .to_string();
+
+        for expected in [
+            "pub trait HostFunctions",
+            "fn get_ledger_sqn (& self) -> HostResult < [u8 ; 4] > ;",
+            "fn trace_num (& self , msg : & str , number : i64) -> HostResult < () > ;",
+            "pub enum HostFunctionSpec { GetLedgerSqn , TraceNum , }",
+            "pub const ALL : & 'static [Self] = & [Self :: GetLedgerSqn , Self :: TraceNum ,]",
+            // The table's row type is generated too, and stays private.
+            "struct HostFnSpec { name : & 'static str , gas : u64 , }",
+            "const fn spec (self) -> HostFnSpec",
+            "Self :: GetLedgerSqn => HostFnSpec { name : \"ldgr_index\" , gas : 60u64 }",
+            "pub const fn wasm_name (self) -> & 'static str",
+            "pub const fn gas (self) -> u64",
+        ] {
+            assert!(generated.contains(expected), "missing {expected:?}");
+        }
+    }
+
+    /// The expansion stands alone: every name in it is either generated here or
+    /// written in the declarations, so it cannot depend on the crate it lands in.
+    #[test]
+    fn names_no_crate_of_its_own() {
+        let generated = expand(quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        })
+        .unwrap()
+        .to_string();
+
+        assert!(!generated.contains("xrpl_host_functions"), "{generated}");
+
+        // `Self::Variant` is the only path the expansion may build: anything else
+        // would reach out of the generated code. Doc comments spell paths without
+        // spaces (`Self::ALL`), so they do not match.
+        for (index, _) in generated.match_indices(" :: ") {
+            assert!(
+                generated[..index].ends_with("Self"),
+                "path out of the expansion at {index}: {generated}"
+            );
+        }
+    }
+
+    /// `spec` is an implementation detail of the two accessors, so it must not
+    /// become part of the ABI crate's public surface.
+    #[test]
+    fn keeps_the_table_row_private() {
+        let generated = expand(quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        })
+        .unwrap()
+        .to_string();
+
+        assert!(!generated.contains("pub struct HostFnSpec"), "{generated}");
+        assert!(!generated.contains("pub const fn spec"), "{generated}");
+    }
+
+    #[test]
+    fn rejects_two_functions_that_share_a_wasm_name() {
+        let messages = messages(quote! {
+            #[gas = 60]
+            #[wasm_name = "trace"]
+            fn trace(&self, msg: &str) -> HostResult<()>;
+
+            #[gas = 70]
+            #[wasm_name = "trace"]
+            fn trace_num(&self, msg: &str, number: i64) -> HostResult<()>;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(
+            messages[0].contains("already imported as `trace`"),
+            "{messages:?}"
+        );
+    }
+
+    /// Names that differ only in underscores collapse to one enum variant.
+    #[test]
+    fn rejects_two_functions_that_share_a_variant() {
+        let messages = messages(quote! {
+            #[gas = 60]
+            #[wasm_name = "a"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+
+            #[gas = 70]
+            #[wasm_name = "b"]
+            fn get_ledger__sqn(&self) -> HostResult<[u8; 4]>;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(
+            messages[0].contains("`GetLedgerSqn` variant"),
+            "{messages:?}"
+        );
+    }
+}

crates/xrpl-host-functions-macros/src/parsed_host_function.rs

@@ -0,0 +1,871 @@
+use proc_macro2::TokenStream;
+use quote::{format_ident, quote};
+use syn::{
+    Attribute, Expr, ExprLit, Ident, Lit, LitStr, PathArguments, ReceiverKind, ReturnType, Safety,
+    Signature, TraitItemFn, Type, TypePath,
+};
+
+use crate::errors;
+
+/// `#[gas = N]`: the base gas charged before the call runs.
+const GAS: &str = "gas";
+/// `#[wasm_name = "..."]`: the name the guest imports the function under.
+const WASM_NAME: &str = "wasm_name";
+/// `///` desugars to `#[doc = "..."]` before macro expansion.
+const DOC: &str = "doc";
+/// The alias every declaration returns its success type through.
+const HOST_RESULT: &str = "HostResult";
+
+/// One entry of a `host_functions!` block: its ABI metadata and its signature.
+pub(crate) struct ParsedHostFunction {
+    pub(crate) gas: u64,
+    /// Kept as the literal the user wrote, so diagnostics and the generated
+    /// string both carry that span.
+    pub(crate) wasm_name: LitStr,
+    /// Doc comments, in source order, to re-emit on the generated items.
+    pub(crate) docs: Vec<Attribute>,
+    /// The enum variant this declaration becomes, spanned at the function name.
+    pub(crate) variant: Ident,
+    pub(crate) signature: Signature,
+}
+
+impl ParsedHostFunction {
+    /// `#[doc …] fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;`
+    pub(crate) fn trait_method(&self) -> TokenStream {
+        let docs = &self.docs;
+        // The declaration is already a trait method: emitted verbatim, so what
+        // the block reads like is what the trait is.
+        let signature = &self.signature;
+
+        quote! {
+            #(#docs)*
+            #signature;
+        }
+    }
+
+    /// `#[doc …] GetLedgerSqn`
+    pub(crate) fn variant_declaration(&self) -> TokenStream {
+        let docs = &self.docs;
+        let variant = &self.variant;
+        quote! {
+            #(#docs)*
+            #variant
+        }
+    }
+
+    /// `Self::GetLedgerSqn => HostFnSpec { name: "ldgr_index", gas: 60u64 }`
+    pub(crate) fn spec_arm(&self) -> TokenStream {
+        let Self {
+            gas,
+            wasm_name,
+            variant,
+            ..
+        } = self;
+        quote! {
+            Self::#variant => HostFnSpec { name: #wasm_name, gas: #gas }
+        }
+    }
+
+    pub(crate) fn parse(function: TraitItemFn) -> syn::Result<Self> {
+        let mut gas = None;
+        let mut wasm_name = None;
+        let mut docs = Vec::new();
+        let mut errors = Vec::new();
+
+        // Tracked separately from `gas`/`wasm_name` so a malformed attribute is
+        // not also reported as a missing one.
+        let mut saw_gas = false;
+        let mut saw_wasm_name = false;
+
+        for attr in function.attrs {
+            if attr.path().is_ident(GAS) {
+                saw_gas = true;
+                if let Err(error) = int_value(&attr).and_then(|v| set_once(&mut gas, v, &attr)) {
+                    errors.push(error);
+                }
+            } else if attr.path().is_ident(WASM_NAME) {
+                saw_wasm_name = true;
+                if let Err(error) =
+                    string_value(&attr).and_then(|v| set_once(&mut wasm_name, v, &attr))
+                {
+                    errors.push(error);
+                }
+            } else if attr.path().is_ident(DOC) {
+                docs.push(attr);
+            } else {
+                errors.push(syn::Error::new_spanned(
+                    &attr,
+                    format!("unexpected attribute `{}`", path_name(&attr)),
+                ));
+            }
+        }
+
+        if !saw_gas {
+            errors.push(syn::Error::new_spanned(
+                &function.sig.ident,
+                format!("missing `#[{GAS} = ...]` attribute"),
+            ));
+        }
+        if !saw_wasm_name {
+            errors.push(syn::Error::new_spanned(
+                &function.sig.ident,
+                format!("missing `#[{WASM_NAME} = \"...\"]` attribute"),
+            ));
+        }
+        if let Some(body) = &function.default {
+            errors.push(syn::Error::new_spanned(
+                body,
+                "a host function is implemented by the host, so it must not have a body",
+            ));
+        }
+        if !function.sig.generics.params.is_empty() || function.sig.generics.where_clause.is_some()
+        {
+            errors.push(syn::Error::new_spanned(
+                &function.sig.ident,
+                "a host function must not be generic: it maps to one wasm import signature",
+            ));
+        }
+        errors.extend(check_receiver(&function.sig).err());
+        errors.extend(check_return_type(&function.sig).err());
+        if let Some(name) = &wasm_name {
+            errors.extend(check_wasm_name(name).err());
+        }
+        reject_modifiers(&function.sig, &mut errors);
+
+        // A name whose PascalCase form is not a legal variant is reported here
+        // rather than emitted, which would either panic or fail downstream.
+        let variant = match variant_ident(&function.sig.ident) {
+            Ok(variant) => Some(variant),
+            Err(error) => {
+                errors.push(error);
+                None
+            }
+        };
+
+        if let Some(error) = errors::combine(errors) {
+            return Err(error);
+        }
+
+        let (Some(gas), Some(wasm_name), Some(variant)) = (gas, wasm_name, variant) else {
+            unreachable!("every absent field is reported above");
+        };
+
+        Ok(Self {
+            gas,
+            wasm_name,
+            docs,
+            variant,
+            signature: function.sig,
+        })
+    }
+}
+
+/// Every declaration carries a receiver, and it is always `&self`.
+///
+/// `&self` is the only receiver that can work: the VM reaches the host through a
+/// shared `&dyn HostFunctions` stored in the wasmi `Store`, and a host that needs
+/// to mutate does so behind interior mutability. The receiver is not part of the
+/// wasm ABI — the guest passes no `self` — so it is uniform across the block.
+fn check_receiver(signature: &Signature) -> syn::Result<()> {
+    let Some(receiver) = signature.receiver() else {
+        return Err(syn::Error::new_spanned(
+            &signature.ident,
+            format!(
+                "a host function must declare its receiver: `fn {}(&self, ...)`",
+                signature.ident
+            ),
+        ));
+    };
+
+    // `&self` and nothing else: not `&mut self`, not `self`/`mut self`, not a
+    // typed `self: Box<Self>`, and not a spelled-out lifetime.
+    if !matches!(receiver.kind, ReceiverKind::Reference(_, None, None)) {
+        return Err(syn::Error::new_spanned(
+            receiver,
+            "a host function's receiver must be exactly `&self`: the VM calls the host \
+             through a shared `&dyn HostFunctions`",
+        ));
+    }
+    Ok(())
+}
+
+/// Every declaration returns `HostResult<T>`, including the ones that yield
+/// nothing (`HostResult<()>`).
+///
+/// One shape for every function is what lets a single dispatch adapter lower them
+/// all: lift the arguments out of guest memory, call the host, then turn `Ok(T)`
+/// into the wire's non-negative `i32` and `Err(e)` into a negative code or a trap.
+/// A function returning a bare `T` would need its own arm.
+fn check_return_type(signature: &Signature) -> syn::Result<()> {
+    const SHAPE: &str = "a host function must return `HostResult<T>` — \
+                         `HostResult<()>` if it yields nothing";
+
+    let ReturnType::Type(_, returned) = &signature.output else {
+        return Err(syn::Error::new_spanned(&signature.ident, SHAPE));
+    };
+
+    let Type::Path(TypePath {
+        qself: None, path, ..
+    }) = &**returned
+    else {
+        return Err(syn::Error::new_spanned(returned, SHAPE));
+    };
+    // The last segment only, so `HostResult<T>` may be written qualified.
+    let Some(last) = path.segments.last() else {
+        return Err(syn::Error::new_spanned(returned, SHAPE));
+    };
+    if last.ident != HOST_RESULT {
+        return Err(syn::Error::new_spanned(returned, SHAPE));
+    }
+
+    // `HostResult` without its success type is `HostResult` the alias, which names
+    // no type; rustc's own message for that is unhelpfully far from the cause.
+    let PathArguments::AngleBracketed(arguments) = &last.arguments else {
+        return Err(syn::Error::new_spanned(
+            returned,
+            format!("`{HOST_RESULT}` needs its success type: `{HOST_RESULT}<T>`"),
+        ));
+    };
+    if arguments.args.len() != 1 {
+        return Err(syn::Error::new_spanned(
+            arguments,
+            format!("`{HOST_RESULT}` takes exactly one type: `{HOST_RESULT}<T>`"),
+        ));
+    }
+    Ok(())
+}
+
+/// `const`, `async`, `unsafe`/`safe` and `extern "…"` have no meaning in the
+/// wasm ABI, and would otherwise pass silently into the generated trait.
+fn reject_modifiers(signature: &Signature, errors: &mut Vec<syn::Error>) {
+    const PLAIN: &str =
+        "a host function must be a plain `fn`: this modifier is not part of the wasm ABI";
+
+    if let Some(constness) = &signature.constness {
+        errors.push(syn::Error::new_spanned(constness, PLAIN));
+    }
+    if let Some(asyncness) = &signature.asyncness {
+        errors.push(syn::Error::new_spanned(asyncness, PLAIN));
+    }
+    match &signature.safety {
+        Safety::Default => {}
+        Safety::Safe(token) => errors.push(syn::Error::new_spanned(token, PLAIN)),
+        Safety::Unsafe(token) => errors.push(syn::Error::new_spanned(token, PLAIN)),
+    }
+    if let Some(abi) = &signature.abi {
+        errors.push(syn::Error::new_spanned(abi, PLAIN));
+    }
+}
+
+/// The wasm import name reaches the engine's import table verbatim, so it is
+/// held to what an import name can sanely be rather than to any string.
+fn check_wasm_name(name: &LitStr) -> syn::Result<()> {
+    let value = name.value();
+    if value.is_empty() {
+        return Err(syn::Error::new_spanned(
+            name,
+            "the wasm name must not be empty",
+        ));
+    }
+    if let Some(character) = value
+        .chars()
+        .find(|c| !c.is_ascii_alphanumeric() && *c != '_')
+    {
+        return Err(syn::Error::new_spanned(
+            name,
+            format!(
+                "a wasm name may only contain `A-Za-z0-9_`, but this one contains {character:?}"
+            ),
+        ));
+    }
+    Ok(())
+}
+
+/// The enum variant a declaration becomes: `get_ledger_sqn` -> `GetLedgerSqn`.
+///
+/// The result carries `ident`'s span, so anything the compiler says about the
+/// variant points at the declaration that produced it.
+fn variant_ident(ident: &Ident) -> syn::Result<Ident> {
+    // `to_string` spells raw identifiers `r#type`; the `r#` is not part of the name.
+    let name = ident.to_string();
+    let name = name.strip_prefix("r#").unwrap_or(&name);
+
+    let mut pascal = String::with_capacity(name.len());
+    let mut capitalize = true;
+    for character in name.chars() {
+        if character == '_' {
+            capitalize = true;
+        } else if capitalize {
+            pascal.extend(character.to_uppercase());
+            capitalize = false;
+        } else {
+            pascal.push(character);
+        }
+    }
+
+    // A name of nothing but underscores leaves `pascal` empty; the original is
+    // already a legal identifier, so keep it.
+    if pascal.is_empty() {
+        return Ok(ident.clone());
+    }
+
+    // `Ident::new` panics on a leading digit (`_2fa` -> `2fa`) and silently
+    // accepts keyword spellings (`self_` -> `Self`), which then fails to parse
+    // where the variant is emitted. Parsing rejects both, without panicking.
+    if let Err(error) = syn::parse_str::<Ident>(&pascal) {
+        return Err(syn::Error::new_spanned(
+            ident,
+            format!(
+                "this name becomes the enum variant `{pascal}`, which is not a valid \
+                 variant name ({error}); rename the host function"
+            ),
+        ));
+    }
+    Ok(format_ident!("{pascal}", span = ident.span()))
+}
+
+/// Records `value`, or reports that the attribute appeared more than once.
+fn set_once<T>(slot: &mut Option<T>, value: T, attr: &Attribute) -> syn::Result<()> {
+    if slot.replace(value).is_some() {
+        return Err(syn::Error::new_spanned(
+            attr,
+            format!("duplicate `{}` attribute", path_name(attr)),
+        ));
+    }
+    Ok(())
+}
+
+fn int_value(attr: &Attribute) -> syn::Result<u64> {
+    match &attr.meta.require_name_value()?.value {
+        Expr::Lit(ExprLit {
+            lit: Lit::Int(int), ..
+        }) => {
+            // `LitInt` keeps the sign in its digits, so `base10_parse::<u64>`
+            // would report a negative value as "invalid digit found in string".
+            if int.base10_digits().starts_with('-') {
+                return Err(syn::Error::new_spanned(
+                    int,
+                    format!("`{}` must not be negative", path_name(attr)),
+                ));
+            }
+            int.base10_parse()
+        }
+        other => Err(syn::Error::new_spanned(
+            other,
+            format!("`{}` expects an integer literal", path_name(attr)),
+        )),
+    }
+}
+
+fn string_value(attr: &Attribute) -> syn::Result<LitStr> {
+    match &attr.meta.require_name_value()?.value {
+        Expr::Lit(ExprLit {
+            lit: Lit::Str(string),
+            ..
+        }) => Ok(string.clone()),
+        other => Err(syn::Error::new_spanned(
+            other,
+            format!("`{}` expects a string literal", path_name(attr)),
+        )),
+    }
+}
+
+/// The attribute's path as written, for diagnostics: `gas`, or `foo::bar`.
+fn path_name(attr: &Attribute) -> String {
+    attr.path()
+        .segments
+        .iter()
+        .map(|segment| segment.ident.to_string())
+        .collect::<Vec<_>>()
+        .join("::")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use quote::ToTokens;
+    use syn::parse_quote;
+
+    /// The message of every diagnostic recorded by one failed `parse`.
+    ///
+    /// `expect_err` is unavailable here: it needs `T: Debug`, and syn only
+    /// implements `Debug` for its AST types under the `extra-traits` feature.
+    fn messages(function: TraitItemFn) -> Vec<String> {
+        let Err(error) = ParsedHostFunction::parse(function) else {
+            panic!("expected parsing to fail");
+        };
+        error.into_iter().map(|error| error.to_string()).collect()
+    }
+
+    fn doc_text(attr: &Attribute) -> String {
+        match &attr.meta.require_name_value().unwrap().value {
+            Expr::Lit(ExprLit {
+                lit: Lit::Str(text),
+                ..
+            }) => text.value(),
+            _ => panic!("doc attribute is not a string literal"),
+        }
+    }
+
+    #[test]
+    fn reads_gas_and_wasm_name() {
+        let parsed = ParsedHostFunction::parse(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        })
+        .unwrap();
+
+        assert_eq!(parsed.gas, 60);
+        assert_eq!(parsed.wasm_name.value(), "ldgr_index");
+        assert_eq!(parsed.signature.ident.to_string(), "get_ledger_sqn");
+        assert_eq!(parsed.variant.to_string(), "GetLedgerSqn");
+        assert!(parsed.docs.is_empty());
+    }
+
+    #[test]
+    fn derives_variant_names_from_function_names() {
+        for (function, variant) in [
+            ("get_ledger_sqn", "GetLedgerSqn"),
+            ("sha512_half", "Sha512Half"),
+            ("trace", "Trace"),
+            ("get_current_ledger_obj_field", "GetCurrentLedgerObjField"),
+            ("r#type", "Type"),
+            ("trace2", "Trace2"),
+            // Pathological, but must not panic: no letters to capitalize.
+            ("__", "__"),
+        ] {
+            let ident = format_ident!("{function}");
+            assert_eq!(
+                variant_ident(&ident).map(|v| v.to_string()).ok(),
+                Some(variant.to_owned()),
+                "{function}"
+            );
+        }
+    }
+
+    /// `_2fa` would PascalCase to `2fa`; building that `Ident` panics, and a
+    /// panic in a proc macro is reported with no useful span at all.
+    #[test]
+    fn rejects_a_name_that_becomes_a_leading_digit() {
+        let messages = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "two_factor"]
+            fn _2fa(&self) -> HostResult<()>;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(
+            messages[0].contains("becomes the enum variant `2fa`"),
+            "{messages:?}"
+        );
+    }
+
+    /// `self_` PascalCases to `Self`, which `Ident::new` accepts and rustc then
+    /// rejects where the variant is emitted. `r#Self` is not a legal escape.
+    #[test]
+    fn rejects_a_name_that_becomes_a_keyword() {
+        for function in ["self_", "_self"] {
+            let ident = format_ident!("{function}");
+            let Err(error) = variant_ident(&ident) else {
+                panic!("expected `{function}` to be rejected");
+            };
+            assert!(
+                error.to_string().contains("variant `Self`"),
+                "{}",
+                error.to_string()
+            );
+        }
+    }
+
+    #[test]
+    fn rejects_negative_gas() {
+        let messages = messages(parse_quote! {
+            #[gas = -5]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert_eq!(messages[0], "`gas` must not be negative");
+    }
+
+    #[test]
+    fn rejects_unusable_wasm_names() {
+        let empty = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = ""]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+        assert_eq!(empty.len(), 1, "{empty:?}");
+        assert_eq!(empty[0], "the wasm name must not be empty");
+
+        let spaced = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+        assert_eq!(spaced.len(), 1, "{spaced:?}");
+        assert!(spaced[0].contains("may only contain"), "{spaced:?}");
+    }
+
+    #[test]
+    fn rejects_signature_modifiers() {
+        for declaration in [
+            quote! { unsafe fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>; },
+            quote! { async fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>; },
+            quote! { const fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>; },
+            quote! { extern "C" fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>; },
+        ] {
+            let function: TraitItemFn = syn::parse2(quote! {
+                #[gas = 60]
+                #[wasm_name = "ldgr_index"]
+                #declaration
+            })
+            .unwrap();
+
+            let messages = messages(function);
+            assert_eq!(messages.len(), 1, "{messages:?}");
+            assert!(messages[0].contains("must be a plain `fn`"), "{messages:?}");
+        }
+    }
+
+    #[test]
+    fn trait_method_keeps_the_declared_receiver_and_ends_in_a_semicolon() {
+        let parsed = ParsedHostFunction::parse(parse_quote! {
+            /// Hashes `data`.
+            #[gas = 2000]
+            #[wasm_name = "sha512_half"]
+            fn sha512_half(&self, data: &[u8]) -> HostResult<[u8; 32]>;
+        })
+        .unwrap();
+
+        // `///` reaches the macro as `#[doc = r"..."]`: rustc's lexer spells doc
+        // comments as raw string literals.
+        let method = parsed.trait_method().to_string();
+        assert!(
+            method.starts_with("# [doc = r\" Hashes `data`.\"]"),
+            "{method}"
+        );
+        assert!(
+            method
+                .contains("fn sha512_half (& self , data : & [u8]) -> HostResult < [u8 ; 32] > ;"),
+            "{method}"
+        );
+    }
+
+    #[test]
+    fn spec_arm_carries_the_name_and_the_gas() {
+        let parsed = ParsedHostFunction::parse(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        })
+        .unwrap();
+
+        assert_eq!(
+            parsed.spec_arm().to_string(),
+            "Self :: GetLedgerSqn => HostFnSpec { name : \"ldgr_index\" , gas : 60u64 }"
+        );
+    }
+
+    #[test]
+    fn keeps_doc_comments_in_source_order() {
+        let parsed = ParsedHostFunction::parse(parse_quote! {
+            /// First line.
+            ///
+            /// Third line.
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        })
+        .unwrap();
+
+        let docs: Vec<_> = parsed.docs.iter().map(doc_text).collect();
+        assert_eq!(docs, vec![" First line.", "", " Third line."]);
+    }
+
+    #[test]
+    fn preserves_parameters_and_return_type() {
+        let traced = ParsedHostFunction::parse(parse_quote! {
+            #[gas = 500]
+            #[wasm_name = "trace"]
+            fn trace(&self, msg: &str, data: &[u8], as_hex: bool) -> HostResult<()>;
+        })
+        .unwrap();
+        // The receiver is `inputs[0]`; the three wasm parameters follow it.
+        assert_eq!(traced.signature.inputs.len(), 4);
+        assert_eq!(
+            traced.signature.output.to_token_stream().to_string(),
+            "-> HostResult < () >"
+        );
+
+        let hashed = ParsedHostFunction::parse(parse_quote! {
+            #[gas = 2000]
+            #[wasm_name = "sha512_half"]
+            fn sha512_half(&self, data: &[u8]) -> HostResult<[u8; HASH_LEN]>;
+        })
+        .unwrap();
+        assert_eq!(
+            hashed.signature.output.to_token_stream().to_string(),
+            "-> HostResult < [u8 ; HASH_LEN] >"
+        );
+    }
+
+    #[test]
+    fn reports_both_missing_attributes_at_once() {
+        let messages = messages(parse_quote! {
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+
+        assert_eq!(messages.len(), 2);
+        assert!(messages[0].contains("missing `#[gas"), "{messages:?}");
+        assert!(messages[1].contains("missing `#[wasm_name"), "{messages:?}");
+    }
+
+    #[test]
+    fn names_the_unexpected_attribute() {
+        let messages = messages(parse_quote! {
+            #[gas = 60]
+            #[wsam_name = "typo"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+
+        // The typo'd attribute, plus the `wasm_name` it failed to be.
+        assert_eq!(messages.len(), 2);
+        assert!(
+            messages.iter().any(|m| m.contains("`wsam_name`")),
+            "{messages:?}"
+        );
+    }
+
+    #[test]
+    fn rejects_wrong_literal_types() {
+        let gas = messages(parse_quote! {
+            #[gas = "60"]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+        assert_eq!(gas.len(), 1, "{gas:?}");
+        assert!(
+            gas[0].contains("`gas` expects an integer literal"),
+            "{gas:?}"
+        );
+
+        let name = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = 7]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+        assert_eq!(name.len(), 1, "{name:?}");
+        assert!(
+            name[0].contains("`wasm_name` expects a string literal"),
+            "{name:?}"
+        );
+    }
+
+    #[test]
+    fn rejects_gas_that_does_not_fit_in_u64() {
+        let messages = messages(parse_quote! {
+            #[gas = 99999999999999999999999]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(messages[0].contains("number too large"), "{messages:?}");
+    }
+
+    #[test]
+    fn rejects_attribute_shapes_other_than_name_value() {
+        let bare = messages(parse_quote! {
+            #[gas]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+        assert_eq!(bare.len(), 1, "{bare:?}");
+        assert!(bare[0].contains("gas = ..."), "{bare:?}");
+
+        let list = messages(parse_quote! {
+            #[gas(60)]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+        assert_eq!(list.len(), 1, "{list:?}");
+    }
+
+    #[test]
+    fn rejects_duplicate_attributes() {
+        let messages = messages(parse_quote! {
+            #[gas = 60]
+            #[gas = 70]
+            #[wasm_name = "ldgr_index"]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+
+        assert_eq!(messages.len(), 2, "{messages:?}");
+        assert!(messages[0].contains("duplicate `gas`"), "{messages:?}");
+        assert!(
+            messages[1].contains("duplicate `wasm_name`"),
+            "{messages:?}"
+        );
+    }
+
+    /// A malformed attribute must not also be reported as an absent one.
+    #[test]
+    fn does_not_report_a_malformed_attribute_as_missing() {
+        let messages = messages(parse_quote! {
+            #[gas = "60"]
+            #[wasm_name = 7]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]>;
+        });
+
+        assert_eq!(messages.len(), 2, "{messages:?}");
+        assert!(
+            !messages.iter().any(|m| m.contains("missing")),
+            "{messages:?}"
+        );
+    }
+
+    #[test]
+    fn rejects_a_body() {
+        let messages = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]> { Ok([0; 4]) }
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(messages[0].contains("must not have a body"), "{messages:?}");
+    }
+
+    #[test]
+    fn rejects_generics() {
+        let parameter = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn<T>(&self) -> HostResult<T>;
+        });
+        assert_eq!(parameter.len(), 1, "{parameter:?}");
+        assert!(
+            parameter[0].contains("must not be generic"),
+            "{parameter:?}"
+        );
+
+        let clause = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult<[u8; 4]> where Self: Sized;
+        });
+        assert_eq!(clause.len(), 1, "{clause:?}");
+    }
+
+    #[test]
+    fn requires_a_receiver() {
+        let messages = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn() -> HostResult<[u8; 4]>;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(
+            messages[0].contains("must declare its receiver: `fn get_ledger_sqn(&self, ...)`"),
+            "{messages:?}"
+        );
+    }
+
+    /// Anything but `&self` would need a host the VM cannot hand out: it holds
+    /// one shared `&dyn HostFunctions` for the whole run.
+    #[test]
+    fn rejects_receivers_other_than_shared_self() {
+        for receiver in [
+            quote! { &mut self },
+            quote! { self },
+            quote! { mut self },
+            quote! { self: Box<Self> },
+            quote! { &'a self },
+        ] {
+            let function: TraitItemFn = syn::parse2(quote! {
+                #[gas = 60]
+                #[wasm_name = "ldgr_index"]
+                fn get_ledger_sqn(#receiver) -> HostResult<[u8; 4]>;
+            })
+            .unwrap_or_else(|_| panic!("`{receiver}` should parse"));
+
+            let messages = messages(function);
+            assert_eq!(messages.len(), 1, "`{receiver}`: {messages:?}");
+            assert!(
+                messages[0].contains("must be exactly `&self`"),
+                "`{receiver}`: {messages:?}"
+            );
+        }
+    }
+
+    /// A bare `T` return would need its own lowering arm, so the uniform shape is
+    /// required rather than inferred.
+    #[test]
+    fn rejects_returns_that_are_not_host_result() {
+        for output in [
+            quote! {},
+            quote! { -> () },
+            quote! { -> [u8; 4] },
+            quote! { -> i32 },
+            quote! { -> Result<[u8; 4], HostError> },
+            quote! { -> impl Iterator<Item = u8> },
+        ] {
+            let function: TraitItemFn = syn::parse2(quote! {
+                #[gas = 60]
+                #[wasm_name = "ldgr_index"]
+                fn get_ledger_sqn(&self) #output;
+            })
+            .unwrap_or_else(|_| panic!("`{output}` should parse"));
+
+            let messages = messages(function);
+            assert_eq!(messages.len(), 1, "`{output}`: {messages:?}");
+            assert!(
+                messages[0].contains("must return `HostResult<T>`"),
+                "`{output}`: {messages:?}"
+            );
+        }
+    }
+
+    /// `HostResult` may be written qualified, since the trait method keeps whatever
+    /// path resolves where the block is written.
+    #[test]
+    fn accepts_a_qualified_host_result() {
+        let parsed = ParsedHostFunction::parse(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> xrpl_host_functions::HostResult<[u8; 4]>;
+        })
+        .unwrap();
+
+        assert!(
+            parsed
+                .trait_method()
+                .to_string()
+                .contains("xrpl_host_functions :: HostResult < [u8 ; 4] >"),
+            "{}",
+            parsed.trait_method()
+        );
+    }
+
+    /// `HostResult` with no success type names no type at all; rustc's own error
+    /// for that lands on the generated trait, far from the declaration.
+    #[test]
+    fn rejects_host_result_without_a_success_type() {
+        let messages = messages(parse_quote! {
+            #[gas = 60]
+            #[wasm_name = "ldgr_index"]
+            fn get_ledger_sqn(&self) -> HostResult;
+        });
+
+        assert_eq!(messages.len(), 1, "{messages:?}");
+        assert!(
+            messages[0].contains("needs its success type"),
+            "{messages:?}"
+        );
+    }
+}

crates/xrpl-host-functions/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "xrpl-host-functions"
+version = "0.1.0"
+edition.workspace = true
+
+[dependencies]
+xrpl-host-functions-macros.path = "../xrpl-host-functions-macros"

crates/xrpl-host-functions/src/lib.rs

@@ -0,0 +1,539 @@
+//! The wasm host ABI: the one place it is declared.
+//!
+//! `host_functions!` turns the declaration block at the bottom of this file into the
+//! [`HostFunctions`] trait a host implements and the [`HostFunctionSpec`] table a
+//! wasm engine registers from.
+//!
+//! The split: hand-written here is the vocabulary the declarations are written in —
+//! [`HostError`], [`TraceDataType`], [`HostResult`], [`HASH_LEN`] — and everything
+//! derived from the declarations is generated. The expansion names nothing this file
+//! does not, so the two sides meet only in the block below.
+//!
+//! So this file is lists — error codes, trace data types, functions. The `macro_rules!`
+//! that expand the first two into enums live in `macros.rs`.
+
+#![no_std]
+
+#[macro_use]
+mod macros;
+
+// Not re-exported: the ABI is declared once, here, and this is the only call site.
+use xrpl_host_functions_macros::host_functions;
+
+host_errors! {
+    Unimplemented = -1,
+    FieldNotFound = -2,
+    BufferTooSmall = -3,
+    NoArray = -4,
+    NotLeafField = -5,
+    LocatorMalformed = -6,
+    SlotOutRange = -7,
+    SlotsFull = -8,
+    EmptySlot = -9,
+    LedgerObjNotFound = -10,
+    OutOfTransferLimit = -11,
+    DataFieldTooLarge = -12,
+    PointerOutOfBounds = -13,
+    NoMemExported = -14,
+    InvalidParams = -15,
+    InvalidAccount = -16,
+    InvalidField = -17,
+    IndexOutOfBounds = -18,
+    FloatInputMalformed = -19,
+    FloatComputationError = -20,
+    /// Internal fatal error.
+    /// User code will never see this error but keep it reserved to not rely on the value.
+    InternalFatal = -2147483648,
+}
+
+/// Convenience alias for the trait's fallible returns.
+pub type HostResult<T> = Result<T, HostError>;
+
+/// A `sha512Half` digest: the first 32 bytes of a SHA-512, as XRPL uses it.
+pub const HASH_LEN: usize = 32;
+
+trace_data_types! {
+    /// 8 little-endian bytes, rendered as a signed decimal.
+    Int64 = 1,
+    /// 8 little-endian bytes, rendered as an unsigned decimal.
+    Uint64 = 2,
+    /// A serialized XRPL float: 12 bytes, mantissa then exponent.
+    Xfloat = 3,
+    /// A 20-byte account ID, rendered as base58.
+    Account = 4,
+    /// A serialized `STAmount`.
+    Amount = 5,
+    /// Raw bytes, hex-encoded.
+    AsHex = 6,
+    /// Bytes rendered verbatim as text.
+    AsText = 7,
+}
+
+host_functions! {
+    /// The sequence number of the ledger being built, as 4 little-endian bytes.
+    #[gas = 60]
+    #[wasm_name = "ldgr_index"]
+    fn get_ledger_sqn(&self, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The close time of the parent (last-closed) ledger, as 4 little-endian bytes.
+    #[gas = 60]
+    #[wasm_name = "parent_ldgr_time"]
+    fn get_parent_ledger_time(&self, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The hash of the parent (last-closed) ledger, as 32 bytes.
+    #[gas = 60]
+    #[wasm_name = "parent_ldgr_hash"]
+    fn get_parent_ledger_hash(&self, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The base fee of the ledger being built, in drops, as 4 little-endian bytes.
+    #[gas = 60]
+    #[wasm_name = "base_fee"]
+    fn get_base_fee(&self, out: &mut [u8]) -> HostResult<usize>;
+
+    /// Whether an amendment is enabled. The input is either its 32-byte id or its
+    /// name; the answer is `1` if enabled and `0` if not. Unlike the getters, this
+    /// reads an input region and returns the flag directly rather than writing bytes.
+    #[gas = 100]
+    #[wasm_name = "amendment_enabled"]
+    fn is_amendment_enabled(&self, amendment: &[u8]) -> HostResult<i32>;
+
+    /// Load the ledger object with the given 32-byte id into a cache slot, so later
+    /// calls can read its fields. `cache_idx` selects the slot (1-based); `0` asks the
+    /// host to assign a free one. Returns the slot used, or a negative error.
+    #[gas = 5000]
+    #[wasm_name = "cache_le"]
+    fn cache_ledger_obj(&self, obj_id: &[u8], cache_idx: i32) -> HostResult<i32>;
+
+    /// The serialized bytes of one field of the transaction being executed, selected
+    /// by its `SField` code.
+    #[gas = 70]
+    #[wasm_name = "tx_field"]
+    fn get_tx_field(&self, field: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The serialized bytes of one field of the current (escrow) ledger object.
+    #[gas = 70]
+    #[wasm_name = "home_le_field"]
+    fn get_current_ledger_obj_field(&self, field: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The serialized bytes of one field of a previously cached ledger object,
+    /// selected by its cache slot and the field's `SField` code.
+    #[gas = 70]
+    #[wasm_name = "le_field"]
+    fn get_ledger_obj_field(&self, cache_idx: i32, field: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The serialized bytes of a nested field of the transaction, reached by a
+    /// `locator`: a path of little-endian `i32` steps (so its byte length is a
+    /// non-zero multiple of 4). Reads the locator region and writes the field bytes.
+    #[gas = 110]
+    #[wasm_name = "tx_inner"]
+    fn get_tx_nested_field(&self, locator: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The serialized bytes of a nested field of the current (escrow) ledger object,
+    /// reached by a `locator`, as with [`HostFunctions::get_tx_nested_field`].
+    #[gas = 110]
+    #[wasm_name = "home_le_inner"]
+    fn get_current_ledger_obj_nested_field(
+        &self,
+        locator: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The serialized bytes of a nested field of a previously cached ledger object,
+    /// selected by its cache slot and reached by a `locator`.
+    #[gas = 110]
+    #[wasm_name = "le_inner"]
+    fn get_ledger_obj_nested_field(
+        &self,
+        cache_idx: i32,
+        locator: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The number of elements in an array field of the transaction, selected by its
+    /// `SField` code. Answers the count directly, or a negative error (`NoArray` if
+    /// the field is not an array). Reads and writes no memory.
+    #[gas = 40]
+    #[wasm_name = "tx_arr_len"]
+    fn get_tx_array_len(&self, field: i32) -> HostResult<i32>;
+
+    /// The number of elements in an array field of the current (escrow) ledger
+    /// object, as with [`HostFunctions::get_tx_array_len`].
+    #[gas = 40]
+    #[wasm_name = "home_le_arr_len"]
+    fn get_current_ledger_obj_array_len(&self, field: i32) -> HostResult<i32>;
+
+    /// The number of elements in an array field of a previously cached ledger object,
+    /// selected by its cache slot and `SField` code.
+    #[gas = 40]
+    #[wasm_name = "le_arr_len"]
+    fn get_ledger_obj_array_len(&self, cache_idx: i32, field: i32) -> HostResult<i32>;
+
+    /// The number of elements in a nested array field of the transaction, reached by a
+    /// `locator`. Reads the locator region and answers the count directly.
+    #[gas = 70]
+    #[wasm_name = "tx_inner_arr_len"]
+    fn get_tx_nested_array_len(&self, locator: &[u8]) -> HostResult<i32>;
+
+    /// The number of elements in a nested array field of the current (escrow) ledger
+    /// object, reached by a `locator`, as with [`HostFunctions::get_tx_nested_array_len`].
+    #[gas = 70]
+    #[wasm_name = "home_le_inner_arr_len"]
+    fn get_current_ledger_obj_nested_array_len(&self, locator: &[u8]) -> HostResult<i32>;
+
+    /// The number of elements in a nested array field of a previously cached ledger
+    /// object, selected by its cache slot and reached by a `locator`.
+    #[gas = 70]
+    #[wasm_name = "le_inner_arr_len"]
+    fn get_ledger_obj_nested_array_len(&self, cache_idx: i32, locator: &[u8]) -> HostResult<i32>;
+
+    /// Verify `signature` over `message` under `pubkey`. Reads the three regions and
+    /// answers `1` if the signature is valid, `0` if not, or a negative error.
+    ///
+    /// GAS DISCREPANCY: this 300 is the value the C-ABI fork registered
+    /// (`rippled-wasm-host-functions`, WasmVM.cpp), which this port follows. The
+    /// prior C++ integration in this tree charged 35000 for the same call — 100x
+    /// more, and closer to the real cost of signature verification. The value is
+    /// consensus-critical, so confirm which is intended before this ships.
+    #[gas = 300]
+    #[wasm_name = "check_sig"]
+    fn check_signature(
+        &self,
+        message: &[u8],
+        signature: &[u8],
+        pubkey: &[u8],
+    ) -> HostResult<i32>;
+
+    /// The 32-byte ledger key (keylet) of an account's `AccountRoot`, computed from a
+    /// 20-byte account id. Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "accountroot_id"]
+    fn account_keylet(&self, account: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an AMM, computed from its two assets. Each asset is a
+    /// byte slice whose length selects its kind (24 = MPT, 20 = XRP, 40 = issued
+    /// currency + issuer). Reads both asset regions and writes the keylet.
+    #[gas = 450]
+    #[wasm_name = "amm_id"]
+    fn amm_keylet(&self, asset1: &[u8], asset2: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Check`, computed from a 20-byte account id and its
+    /// sequence number. `seq` is the guest's `u32` carried as its `i32` bit pattern.
+    /// Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "check_id"]
+    fn check_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Credential`, computed from the 20-byte subject and
+    /// issuer account ids and a credential-type byte string. Reads all three regions
+    /// and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "credential_id"]
+    fn credential_keylet(
+        &self,
+        subject: &[u8],
+        issuer: &[u8],
+        credential_type: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Delegate` object, computed from the 20-byte account
+    /// and the account it authorizes. Reads both account regions and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "delegate_id"]
+    fn delegate_keylet(
+        &self,
+        account: &[u8],
+        authorize: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `DepositPreauth`, computed from the 20-byte account and
+    /// the account it authorizes to deposit. Reads both account regions and writes the
+    /// keylet.
+    #[gas = 350]
+    #[wasm_name = "deposit_preauth_id"]
+    fn deposit_preauth_keylet(
+        &self,
+        account: &[u8],
+        authorize: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an account's `DID`, computed from its 20-byte account id.
+    /// Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "did_id"]
+    fn did_keylet(&self, account: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `Escrow`, computed from the 20-byte owner account and
+    /// its sequence number. `seq` is the guest's `u32` carried as its `i32` bit
+    /// pattern. Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "escrow_id"]
+    fn escrow_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `RippleState` (trust line), computed from two 20-byte
+    /// account ids and a 20-byte currency. Reads all three regions and writes the
+    /// keylet.
+    #[gas = 400]
+    #[wasm_name = "trustline_id"]
+    fn trust_line_keylet(
+        &self,
+        account1: &[u8],
+        account2: &[u8],
+        currency: &[u8],
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `MPTokenIssuance`, computed from the 20-byte issuer
+    /// account and its sequence number. `seq` is the guest's `u32` carried as its
+    /// `i32` bit pattern. Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "mpt_issuance_id"]
+    fn mptoken_issuance_keylet(
+        &self,
+        issuer: &[u8],
+        seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `MPToken`, computed from a 24-byte MPT issuance id and
+    /// the 20-byte holder account. Reads both regions and writes the keylet.
+    #[gas = 500]
+    #[wasm_name = "mptoken_id"]
+    fn mptoken_keylet(&self, mptid: &[u8], holder: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `NFTokenOffer`, computed from the 20-byte owner account
+    /// and its sequence number. `seq` is the guest's `u32` carried as its `i32` bit
+    /// pattern. Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "nft_offer_id"]
+    fn nftoken_offer_keylet(
+        &self,
+        account: &[u8],
+        seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `Offer`, computed from the 20-byte owner account and
+    /// its sequence number. `seq` is the guest's `u32` carried as its `i32` bit
+    /// pattern. Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "offer_id"]
+    fn offer_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of an `Oracle`, computed from the 20-byte owner account and
+    /// its document id. `doc_id` is the guest's `u32` carried as its `i32` bit pattern.
+    /// Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "oracle_id"]
+    fn oracle_keylet(&self, account: &[u8], doc_id: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `PayChannel`, computed from the 20-byte source account,
+    /// the 20-byte destination account, and the channel's sequence number. `seq` is the
+    /// guest's `u32` carried as its `i32` bit pattern. Reads both account regions and
+    /// writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "paychan_id"]
+    fn paychannel_keylet(
+        &self,
+        account: &[u8],
+        destination: &[u8],
+        seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `PermissionedDomain`, computed from the 20-byte owner
+    /// account and its sequence number. `seq` is the guest's `u32` carried as its `i32`
+    /// bit pattern. Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "permissioned_domain_id"]
+    fn permissioned_domain_keylet(
+        &self,
+        account: &[u8],
+        seq: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `SignerList`, computed from its 20-byte owner account.
+    /// Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "signers_id"]
+    fn signer_list_keylet(&self, account: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Ticket`, computed from the 20-byte owner account and its
+    /// ticket sequence number. `seq` is the guest's `u32` carried as its `i32` bit
+    /// pattern. Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "ticket_id"]
+    fn ticket_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 32-byte keylet of a `Vault`, computed from the 20-byte owner account and its
+    /// sequence number. `seq` is the guest's `u32` carried as its `i32` bit pattern.
+    /// Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "vault_id"]
+    fn vault_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The XRPL `sha512Half` of `data`: the first [`HASH_LEN`] bytes of its SHA-512.
+    #[gas = 2000]
+    #[wasm_name = "sha512_half"]
+    fn sha512_half(&self, data: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// Writes `msg` to the trace log, followed by `data` rendered as `data_type` says.
+    ///
+    /// The one declaration whose wasm function has **no result**: this node's own log
+    /// is its only effect, so a guest is told nothing. An `Err` from a host therefore
+    /// reaches it in no form, and only the host-fatal ones do anything at all.
+    ///
+    /// It is also the one declaration that is **not** the wasm parameter order.
+    /// `data_type` is the third wasm parameter, between the two regions, because that
+    /// is where xrpld's `trace_proto` and the guest stdlib put it; `register.rs` takes
+    /// the arguments in wasm order and calls this in declaration order.
+    #[gas = 30]
+    #[wasm_name = "trace"]
+    fn trace(&self, msg: &str, data: &[u8], data_type: TraceDataType) -> HostResult<()>;
+
+    /// Stores `data` as the current object's data field, replacing whatever was there,
+    /// and returns the number of bytes stored. Reads the data region; `DataFieldTooLarge`
+    /// if it exceeds the host's limit.
+    #[gas = 1000]
+    #[wasm_name = "set_data"]
+    fn update_data(&self, data: &[u8]) -> HostResult<i32>;
+
+    /// The URI of the `NFToken` with id `nft_id` (32 bytes) held by the 20-byte
+    /// `account`. Reads both regions and writes the URI bytes.
+    #[gas = 5000]
+    #[wasm_name = "nft_uri"]
+    fn get_nft(&self, account: &[u8], nft_id: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The 20-byte issuer account encoded in the `NFToken` id `nft_id` (32 bytes).
+    /// Reads the id region and writes the issuer bytes.
+    #[gas = 70]
+    #[wasm_name = "nft_issuer"]
+    fn get_nft_issuer(&self, nft_id: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The taxon encoded in the `NFToken` id `nft_id` (32 bytes). Reads the id region
+    /// and writes the taxon as its four little-endian bytes.
+    #[gas = 60]
+    #[wasm_name = "nft_taxon"]
+    fn get_nft_taxon(&self, nft_id: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    /// The flags encoded in the `NFToken` id `nft_id` (32 bytes). Reads the id region
+    /// and returns the flags as the call's scalar result.
+    #[gas = 60]
+    #[wasm_name = "nft_flags"]
+    fn get_nft_flags(&self, nft_id: &[u8]) -> HostResult<i32>;
+
+    /// The transfer fee encoded in the `NFToken` id `nft_id` (32 bytes). Reads the id
+    /// region and returns the fee as the call's scalar result.
+    #[gas = 60]
+    #[wasm_name = "nft_xfer_fee"]
+    fn get_nft_transfer_fee(&self, nft_id: &[u8]) -> HostResult<i32>;
+
+    /// The sequence number encoded in the `NFToken` id `nft_id` (32 bytes). Reads the
+    /// id region and writes the sequence as its four little-endian bytes.
+    #[gas = 60]
+    #[wasm_name = "nft_serial"]
+    fn get_nft_sequence(&self, nft_id: &[u8], out: &mut [u8]) -> HostResult<usize>;
+
+    // A "float" here is an XRPL `Number` in its serialized form: a byte blob the guest
+    // holds opaquely and hands back to these functions. Inputs and outputs that are
+    // floats are byte regions; `mode` is the rounding mode, a scalar the guest chooses.
+
+    /// A float built from the signed integer `x` under rounding `mode`. Writes the
+    /// float bytes; no input region.
+    #[gas = 100]
+    #[wasm_name = "float_from_int"]
+    fn float_from_int(&self, x: i64, mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// A float built from the unsigned integer in the 8-byte region `x` under rounding
+    /// `mode`. Reads the integer region and writes the float bytes.
+    #[gas = 130]
+    #[wasm_name = "float_from_uint"]
+    fn float_from_uint(&self, x: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// A float built from the serialized `STAmount` in `amount` under rounding `mode`.
+    /// Reads the amount region and writes the float bytes.
+    #[gas = 150]
+    #[wasm_name = "float_from_stamount"]
+    fn float_from_stamount(&self, amount: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// A float built from the serialized `STNumber` in `number` under rounding `mode`.
+    /// Reads the number region and writes the float bytes.
+    #[gas = 150]
+    #[wasm_name = "float_from_stnumber"]
+    fn float_from_stnumber(&self, number: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float `x` rounded to a signed integer under rounding `mode`. Reads the float
+    /// region and writes the integer as its eight little-endian bytes.
+    #[gas = 130]
+    #[wasm_name = "float_to_int"]
+    fn float_to_int(&self, x: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float `x` split into its mantissa and exponent. Reads the float region and
+    /// writes the mantissa (eight little-endian bytes) and the exponent (four little-
+    /// endian bytes) to two separate output regions.
+    #[gas = 130]
+    #[wasm_name = "float_to_mant_exp"]
+    fn float_to_mant_exp(
+        &self,
+        x: &[u8],
+        mantissa_out: &mut [u8],
+        exponent_out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// A float built from `mantissa` and `exponent` under rounding `mode`. Writes the
+    /// float bytes; no input region.
+    #[gas = 100]
+    #[wasm_name = "float_from_mant_exp"]
+    fn float_from_mant_exp(
+        &self,
+        mantissa: i64,
+        exponent: i32,
+        mode: i32,
+        out: &mut [u8],
+    ) -> HostResult<usize>;
+
+    /// Compares floats `x` and `y`, returning a negative, zero, or positive scalar as
+    /// `x` is less than, equal to, or greater than `y`. Reads both float regions.
+    #[gas = 80]
+    #[wasm_name = "float_cmp"]
+    fn float_compare(&self, x: &[u8], y: &[u8]) -> HostResult<i32>;
+
+    /// The float sum `x + y` under rounding `mode`. Reads both float regions and writes
+    /// the result bytes.
+    #[gas = 160]
+    #[wasm_name = "float_add"]
+    fn float_add(&self, x: &[u8], y: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float difference `x - y` under rounding `mode`. Reads both float regions and
+    /// writes the result bytes.
+    #[gas = 160]
+    #[wasm_name = "float_sub"]
+    fn float_subtract(&self, x: &[u8], y: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float product `x * y` under rounding `mode`. Reads both float regions and
+    /// writes the result bytes.
+    #[gas = 300]
+    #[wasm_name = "float_mult"]
+    fn float_multiply(&self, x: &[u8], y: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float quotient `x / y` under rounding `mode`. Reads both float regions and
+    /// writes the result bytes.
+    #[gas = 300]
+    #[wasm_name = "float_div"]
+    fn float_divide(&self, x: &[u8], y: &[u8], mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The `n`-th root of the float `x` under rounding `mode`. Reads the float region
+    /// and writes the result bytes.
+    #[gas = 5500]
+    #[wasm_name = "float_root"]
+    fn float_root(&self, x: &[u8], n: i32, mode: i32, out: &mut [u8]) -> HostResult<usize>;
+
+    /// The float `x` raised to the power `n` under rounding `mode`. Reads the float
+    /// region and writes the result bytes.
+    #[gas = 5500]
+    #[wasm_name = "float_pow"]
+    fn float_power(&self, x: &[u8], n: i32, mode: i32, out: &mut [u8]) -> HostResult<usize>;
+}

crates/xrpl-host-functions/src/macros.rs

@@ -0,0 +1,102 @@
+//! The `macro_rules!` behind the two hand-listed enums, [`crate::HostError`] and
+//! [`crate::TraceDataType`].
+//!
+//! Each takes one list of `Variant = code,` and expands the enum together with the
+//! `ALL`/`code`/`from_code` set that must not fall behind it. The lists themselves stay
+//! in `lib.rs`, beside the `host_functions!` block.
+
+/// Declares [`crate::HostError`] from one list: the variants, `HostError::ALL` and
+/// `HostError::from_code`'s table all expand from the codes given.
+///
+/// One list is what makes `ALL` complete. Rust cannot enumerate an enum's
+/// variants — an exhaustive `match` forces an arm per variant but gives nothing to
+/// iterate — so a hand-written `ALL` beside a hand-written enum could only be kept
+/// in step by review, and `ALL`'s whole purpose is to be the set a test can trust.
+/// A code added to the list gains its `ALL` entry and its `from_code` arm by
+/// construction. `HostFunctionSpec::ALL` is complete the same way, from the
+/// `host_functions!` block.
+macro_rules! host_errors {
+    ($($(#[$doc:meta])* $variant:ident = $code:literal,)+) => {
+        /// Error codes a host function may return.
+        ///
+        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+        #[repr(i32)]
+        pub enum HostError {
+            $($(#[$doc])* $variant = $code,)+
+        }
+
+        impl HostError {
+            /// Every error a host function may return, in code order.
+            ///
+            /// The complete set, and complete by construction: a wasm engine's
+            /// split between the codes it hands the guest and the conditions it
+            /// traps on is a decision per variant, so the test that checks the
+            /// split iterates this and a code added to the ABI cannot slip past it.
+            pub const ALL: &'static [HostError] = &[$(HostError::$variant,)+];
+
+            /// The negative wire value a failed call returns. Every code but
+            /// `InternalFatal` is one a guest reads off that value.
+            #[inline]
+            pub const fn code(self) -> i32 {
+                self as i32
+            }
+
+            /// Reconstruct a `HostError` from its wire code.
+            ///
+            /// A code this ABI does not define is `InternalFatal`: an answer the
+            /// caller cannot act on is the call not having been served, and that is
+            /// the variant which says so. Positive values are not errors at all and go
+            /// the same way, since this is reached only once a negative return has
+            /// been read as a failure.
+            pub const fn from_code(code: i32) -> HostError {
+                match code {
+                    $($code => HostError::$variant,)+
+                    _ => HostError::InternalFatal,
+                }
+            }
+        }
+    };
+}
+
+/// Declares [`crate::TraceDataType`] from one list, so `TraceDataType::ALL`,
+/// `TraceDataType::code` and `TraceDataType::from_code` cannot fall behind the
+/// variants — the reason `host_errors!` above is written this way.
+macro_rules! trace_data_types {
+    ($($(#[$doc:meta])* $variant:ident = $code:literal,)+) => {
+        /// How [`HostFunctions::trace`] is to read its data buffer.
+        ///
+        /// The discriminants are wire values shared with the guest stdlib: append only,
+        /// never renumber. They start at 1, so a zeroed argument names no type rather
+        /// than the first one.
+        ///
+        /// This is the declaration a guest and a host both compile against. The host
+        /// side needs a second one — `cxx` cannot be a dependency here, since this
+        /// crate also links into the guest — so `xrpl-wasm-vm-ffi` declares a shared
+        /// enum for C++ and converts, exhaustively, from this.
+        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+        #[repr(i32)]
+        pub enum TraceDataType {
+            $($(#[$doc])* $variant = $code,)+
+        }
+
+        impl TraceDataType {
+            /// Every data type a guest may name, in code order.
+            pub const ALL: &'static [TraceDataType] = &[$(TraceDataType::$variant,)+];
+
+            /// The wire value a guest passes to name this type.
+            #[inline]
+            pub const fn code(self) -> i32 {
+                self as i32
+            }
+
+            /// The type `code` names, or `None`: the engine drops a call it cannot
+            /// read rather than guessing at a rendering the guest did not ask for.
+            pub const fn from_code(code: i32) -> Option<TraceDataType> {
+                match code {
+                    $($code => Some(TraceDataType::$variant),)+
+                    _ => None,
+                }
+            }
+        }
+    };
+}

crates/xrpl-host-functions/tests/expansion_hygiene.rs

@@ -0,0 +1,34 @@
+//! `host_functions!` must work outside the crate that declares the ABI: the only
+//! names its expansion needs are the ones the declarations themselves spell.
+
+use xrpl_host_functions::HostResult;
+use xrpl_host_functions_macros::host_functions;
+
+host_functions! {
+    /// Answers with the number it was given.
+    #[gas = 7]
+    #[wasm_name = "ping"]
+    fn ping(&self, number: i32) -> HostResult<i32>;
+}
+
+struct Host;
+
+impl HostFunctions for Host {
+    fn ping(&self, number: i32) -> HostResult<i32> {
+        Ok(number)
+    }
+}
+
+#[test]
+fn the_generated_table_stands_on_its_own() {
+    assert_eq!(HostFunctionSpec::ALL.len(), 1);
+    assert_eq!(HostFunctionSpec::Ping.wasm_name(), "ping");
+    assert_eq!(HostFunctionSpec::Ping.gas(), 7);
+}
+
+/// The generated trait is implementable from another crate, which is the point of
+/// declaring the ABI in a library at all.
+#[test]
+fn the_generated_trait_is_implementable_here() {
+    assert_eq!(Host.ping(3), Ok(3));
+}

crates/xrpl-host-functions/tests/host_errors.rs

@@ -0,0 +1,102 @@
+//! Exercises what `host_errors!` generates: the wire codes, the set
+//! [`HostError::ALL`] names, and the round trip between them.
+//!
+//! The codes are consensus input — they are what a guest reads off a failed host
+//! call — so they are pinned here as literals and derived everywhere else.
+
+use xrpl_host_functions::HostError;
+
+/// The whole set, written out in the order `ALL` gives it: the one place the wire
+/// codes appear as literals, and a deliberate change-detector, since a code that
+/// moves changes what every deployed guest is told.
+#[test]
+fn the_error_table_matches_the_declarations() {
+    let table: Vec<(HostError, i32)> = HostError::ALL
+        .iter()
+        .map(|&error| (error, error.code()))
+        .collect();
+
+    assert_eq!(
+        table,
+        [
+            (HostError::Unimplemented, -1),
+            (HostError::FieldNotFound, -2),
+            (HostError::BufferTooSmall, -3),
+            (HostError::NoArray, -4),
+            (HostError::NotLeafField, -5),
+            (HostError::LocatorMalformed, -6),
+            (HostError::SlotOutRange, -7),
+            (HostError::SlotsFull, -8),
+            (HostError::EmptySlot, -9),
+            (HostError::LedgerObjNotFound, -10),
+            (HostError::OutOfTransferLimit, -11),
+            (HostError::DataFieldTooLarge, -12),
+            (HostError::PointerOutOfBounds, -13),
+            (HostError::NoMemExported, -14),
+            (HostError::InvalidParams, -15),
+            (HostError::InvalidAccount, -16),
+            (HostError::InvalidField, -17),
+            (HostError::IndexOutOfBounds, -18),
+            (HostError::FloatInputMalformed, -19),
+            (HostError::FloatComputationError, -20),
+            (HostError::InternalFatal, i32::MIN),
+        ]
+    );
+}
+
+/// The guest-facing set is `-1 ..= -20` and nothing else: those entries are xrpld's
+/// `HostFunctionError`, and each is a code some contract may read.
+///
+/// `InternalFatal` is the one deliberate exception, exempted by name rather than by
+/// widening the range: a condition with no number a contract can act on needs no number
+/// in the range a contract reads, and holding it at `i32::MIN` is what keeps it from
+/// ever colliding with a code appended to xrpld's list.
+#[test]
+fn every_code_but_the_sentinel_is_in_the_shared_range() {
+    let shared: Vec<HostError> = HostError::ALL
+        .iter()
+        .copied()
+        .filter(|&error| error != HostError::InternalFatal)
+        .collect();
+
+    let outside: Vec<HostError> = shared
+        .iter()
+        .copied()
+        .filter(|error| !(-20..=-1).contains(&error.code()))
+        .collect();
+
+    assert!(outside.is_empty(), "outside -1..=-20: {outside:?}");
+    assert_eq!(shared.len(), 20);
+    assert_eq!(HostError::InternalFatal.code(), i32::MIN);
+    assert_eq!(HostError::ALL.len(), 21);
+}
+
+/// Every code a guest can be handed comes back as the error that produced it, so a
+/// caller reading a negative return value recovers the condition and not a
+/// neighbouring one. The table above pins the numbers; this adds only the round
+/// trip.
+#[test]
+fn every_wire_code_round_trips_back_to_its_error() {
+    for &error in HostError::ALL {
+        assert_eq!(HostError::from_code(error.code()), error, "{error:?}");
+    }
+}
+
+/// A code from outside the set is `InternalFatal`: a host answering something this ABI
+/// does not define has not served the call, whatever it meant by it, and success is not
+/// an error at all.
+///
+/// `-21` is the code xrpld would append next, so it is the one that decides whether a
+/// list this crate has not caught up with reaches a guest or stops the run. `i32::MIN +
+/// 1` is next to the sentinel and unassigned, which is what makes the sentinel a value
+/// rather than a range.
+#[test]
+fn a_code_outside_the_set_is_internal_fatal() {
+    for code in [-21, i32::MIN + 1, 0, 1, i32::MAX] {
+        assert_eq!(
+            HostError::from_code(code),
+            HostError::InternalFatal,
+            "{code}"
+        );
+    }
+}

crates/xrpl-wasm-testkit/Cargo.toml

@@ -1,10 +1,11 @@
 [package]
-name = "rs-hello_world"
+name = "xrpl-wasm-testkit"
 version = "0.1.0"
 edition.workspace = true
 
 [lib]
-crate-type = ["staticlib"]
+crate-type = ["staticlib", "rlib"]
 
 [dependencies]
 cxx.workspace = true
+wat = "1"

crates/xrpl-wasm-testkit/src/lib.rs

@@ -0,0 +1,49 @@
+//! Assembles WebAssembly text for the C++ test suite. **Test-only.**
+//!
+//! A crate of its own rather than an entry on `xrpl-wasm-vm-ffi`, and the separation is the
+//! point. The engine pins `wasmi = { default-features = false }` precisely so a text
+//! assembler cannot reach the consensus path — wasmi's `wat` feature is on by default and
+//! makes `Module::new` accept text as readily as binary, which would make a transaction's
+//! validity a build flag (review finding A5). Putting `compile_wat` on the production bridge
+//! would link `wat` into xrpld even if nothing called it.
+//!
+//! Linked only into `xrpl_tests`, never into `libxrpl` or `xrpld`, so "no assembler in the
+//! shipped node" is a property of the link graph rather than a flag someone can flip.
+#![deny(rustdoc::broken_intra_doc_links)]
+
+#[cxx::bridge(namespace = "rs::wasm_testkit")]
+mod ffi {
+    extern "Rust" {
+        /// Assemble `wat` to a wasm module.
+        ///
+        /// Throws `rust::Error` on invalid input, which is what a test wants: a typo in a
+        /// fixture should fail the test that holds it, at the line that holds it.
+        fn compile_wat(wat: &str) -> Result<Vec<u8>>;
+    }
+}
+
+fn compile_wat(wat: &str) -> Result<Vec<u8>, wat::Error> {
+    wat::parse_str(wat)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::compile_wat;
+
+    #[test]
+    fn a_module_assembles_to_something_beginning_with_the_wasm_magic() {
+        let wasm = compile_wat("(module)").expect("assembles");
+
+        assert_eq!(&wasm[..4], b"\0asm");
+    }
+
+    #[test]
+    fn a_typo_is_an_error_rather_than_a_module() {
+        let error = compile_wat("(module (func (export").expect_err("must not assemble");
+
+        assert!(
+            !error.to_string().is_empty(),
+            "the error has to say something"
+        );
+    }
+}

crates/xrpl-wasm-vm-ffi/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "xrpl-wasm-vm-ffi"
+version = "0.1.0"
+edition.workspace = true
+
+[lib]
+crate-type = ["staticlib", "rlib"]
+
+[dependencies]
+cxx.workspace = true
+xrpl-host-functions = { path = "../xrpl-host-functions" }
+xrpl-wasm-vm = { path = "../xrpl-wasm-vm" }

crates/xrpl-wasm-vm/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "xrpl-wasm-vm"
+version = "0.1.0"
+edition.workspace = true
+
+[dependencies]
+wasmi = { version = "1.1.0", default-features = false, features = ["std"] }
+xrpl-host-functions = { path = "../xrpl-host-functions" }
+
+[dev-dependencies]
+wat = "1"

crates/xrpl-wasm-vm/src/abi.rs

@@ -0,0 +1,824 @@
+use crate::region::Region;
+use crate::vm::{MAX_FIELD_BYTES, VmState};
+use wasmi::{Caller, Memory};
+use xrpl_host_functions::{HostError, HostFunctionSpec, HostFunctions, HostResult};
+
+/// A condition that stops the run. It is a property of the run rather than an answer
+/// to a call, so it reaches no guest and carries no wire code — which is why it is
+/// not a [`HostError`]: no host can report one and no contract can read one.
+///
+/// The three are the outcomes a host call can end a run with, and
+/// `From<Fault> for RunError` in `vm.rs` is where each gets its name.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum Fault {
+    /// This call's charge would take the meter below zero. The guest exhausting the
+    /// meter with its own instructions reaches [`crate::vm::RunError::OutOfGas`] by
+    /// wasmi's `OutOfFuel` trap instead, never through here.
+    OutOfGas,
+    /// The call could not be served: either the host said so, or this engine's own
+    /// fuel meter did not answer.
+    Internal,
+    /// There is no linear memory to work in — the module exports none, or the call
+    /// came from a start section, which runs before there is an instance.
+    NoMemory,
+}
+
+/// How a host call fails: with a code the guest reads off the return value, or with a
+/// [`Fault`] that stops the run.
+///
+/// **The variant picks the channel.** [`to_wire`] reads it rather than asking a
+/// predicate, so the two cannot disagree, and a [`FatalHostError`] cannot be built
+/// around something a guest was supposed to see.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum CallError {
+    Code(HostError),
+    Fatal(Fault),
+}
+
+/// A host call's result inside the engine: [`HostResult`] plus the faults only the
+/// engine can raise.
+pub(crate) type CallResult<T> = Result<T, CallError>;
+
+/// Which channel a host's answer takes, decided once, here.
+///
+/// Three codes stop the run instead of reaching the contract that asked. Each says the
+/// call was not served at all — the host could not do it, it has not been wired, or
+/// there is nowhere to put the answer — and a contract has no business interpreting
+/// any of them, so it is told nothing and the run ends. Every other code is the
+/// contract's to read.
+impl From<HostError> for CallError {
+    fn from(error: HostError) -> CallError {
+        match error {
+            HostError::InternalFatal => CallError::Fatal(Fault::Internal),
+            HostError::Unimplemented => CallError::Fatal(Fault::Internal),
+            HostError::NoMemExported => CallError::Fatal(Fault::NoMemory),
+            code => CallError::Code(code),
+        }
+    }
+}
+
+/// The payload a trap carries so [`crate::vm::run`] can name the outcome without
+/// parsing a message. Holds a [`Fault`], so by construction no guest-visible code can
+/// leave through this channel.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct FatalHostError(pub(crate) Fault);
+
+impl wasmi::errors::HostError for FatalHostError {}
+
+impl core::fmt::Display for FatalHostError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        write!(f, "host call refused: {:?}", self.0)
+    }
+}
+
+/// Charge the call's gas, run its body, put the result on the wire. The one path
+/// every registered closure takes, so gas cannot be forgotten.
+pub(crate) fn charged(
+    caller: &mut Caller<'_, VmState<'_>>,
+    op: HostFunctionSpec,
+    body: impl FnOnce(&mut Caller<'_, VmState<'_>>) -> CallResult<i32>,
+) -> Result<i32, wasmi::Error> {
+    to_wire(charge(caller, op.gas()).and_then(|()| body(caller)))
+}
+
+/// [`charged`] for a call the guest gets no answer from: its wasm function has no
+/// result, so a soft error has nowhere to go and is dropped. The gas is charged first
+/// and charged whatever happens after, so the cost is all such a call leaves behind.
+///
+/// Only `trace` takes this path.
+pub(crate) fn charged_unreported(
+    caller: &mut Caller<'_, VmState<'_>>,
+    op: HostFunctionSpec,
+    body: impl FnOnce(&mut Caller<'_, VmState<'_>>) -> CallResult<()>,
+) -> Result<(), wasmi::Error> {
+    dropped(charge(caller, op.gas()).and_then(|()| body(caller)))
+}
+
+/// [`to_wire`] for a call with no result: there is no return value to encode a code
+/// in, so it is dropped. A [`Fault`] still stops the run — that is a property of the
+/// run, not an answer to the call.
+fn dropped(result: CallResult<()>) -> Result<(), wasmi::Error> {
+    match result {
+        Err(CallError::Fatal(fault)) => Err(wasmi::Error::host(FatalHostError(fault))),
+        _ => Ok(()),
+    }
+}
+
+fn to_wire(result: CallResult<i32>) -> Result<i32, wasmi::Error> {
+    match result {
+        Ok(value) => Ok(value),
+        Err(CallError::Code(error)) => Ok(error.code()),
+        Err(CallError::Fatal(fault)) => Err(wasmi::Error::host(FatalHostError(fault))),
+    }
+}
+
+/// Deduct `cost` fuel; [`Fault::OutOfGas`] if it would go negative.
+///
+/// A meter that will not answer is this crate's own defect, not the contract's, so it
+/// is [`Fault::Internal`] rather than a number a guest could act on.
+fn charge<T>(caller: &mut Caller<'_, T>, cost: u64) -> CallResult<()> {
+    let remaining = caller
+        .get_fuel()
+        .map_err(|_| CallError::Fatal(Fault::Internal))?;
+    match remaining.checked_sub(cost) {
+        Some(left) => caller
+            .set_fuel(left)
+            .map_err(|_| CallError::Fatal(Fault::Internal)),
+        None => {
+            let _ = caller.set_fuel(0);
+            Err(CallError::Fatal(Fault::OutOfGas))
+        }
+    }
+}
+
+fn charge_transfer(state: &VmState<'_>, n: usize) -> Result<(), HostError> {
+    let n = n as u64;
+    let remaining = state.transfer_budget.get();
+    match remaining.checked_sub(n) {
+        Some(left) => {
+            state.transfer_budget.set(left);
+            Ok(())
+        }
+        None => Err(HostError::OutOfTransferLimit),
+    }
+}
+
+fn memory(caller: &Caller<'_, VmState<'_>>) -> CallResult<Memory> {
+    caller
+        .data()
+        .memory
+        .ok_or(CallError::Fatal(Fault::NoMemory))
+}
+
+/// [`Region::read`] of the guest's memory, for a call that reads and writes nothing
+/// back (`trace`).
+pub(crate) fn read_borrowed<'a>(
+    caller: &'a Caller<'_, VmState<'_>>,
+    input: Region,
+) -> CallResult<&'a [u8]> {
+    let mem = memory(caller)?;
+    Ok(input.read(mem.data(caller))?)
+}
+
+/// Decode a guest `u32` argument — a keylet's sequence number or document id — from
+/// its four little-endian bytes, carried on to the host as its `i32` bit pattern.
+///
+/// The ABI transports these as a 4-byte region rather than a wasm scalar (the guest
+/// SDK passes `seq.to_le_bytes()`), so the region must be exactly four bytes;
+/// `InvalidParams` otherwise, matching the C-ABI wrapper's `getDataUInt32`.
+pub(crate) fn read_u32_arg(bytes: &[u8]) -> HostResult<i32> {
+    let arr: [u8; 4] = bytes.try_into().map_err(|_| HostError::InvalidParams)?;
+    Ok(i32::from_le_bytes(arr))
+}
+
+/// Service a call whose answer is bytes, written straight into the guest's output
+/// region.
+///
+/// **`fill` returns the value's true length, not what it wrote**: a host holding 64
+/// bytes and offered room for 4 writes nothing and answers `64`, which is how the
+/// guest learns the size to ask for. So `n` is bounded by neither the region nor the
+/// cap, and both checks below are reachable.
+pub(crate) fn write_into(
+    caller: &mut Caller<'_, VmState<'_>>,
+    out: Region,
+    fill: impl FnOnce(&dyn HostFunctions, &mut [u8]) -> HostResult<usize>,
+) -> CallResult<i32> {
+    let range = out.range()?;
+    let cap = range.len();
+    let mem = memory(caller)?;
+    let host: &dyn HostFunctions = caller.data().host;
+    // Bounds-checked over the guest's whole declared region, so a buffer running
+    // past memory is a wrong pointer rather than a truncated prefix being served…
+    let buf = mem
+        .data_mut(&mut *caller)
+        .get_mut(range)
+        .ok_or(HostError::PointerOutOfBounds)?;
+    // …of which only the field cap is writable, so no call can exceed it whatever
+    // the guest declared.
+    let buf = &mut buf[..cap.min(MAX_FIELD_BYTES)];
+
+    let n = fill(host, buf)?;
+
+    if n > MAX_FIELD_BYTES {
+        return Err(HostError::DataFieldTooLarge.into());
+    }
+    if n > cap {
+        return Err(HostError::BufferTooSmall.into());
+    }
+    charge_transfer(caller.data(), n)?;
+    #[expect(
+        clippy::cast_possible_truncation,
+        clippy::cast_possible_wrap,
+        reason = "`n > MAX_FIELD_BYTES` returned above, and the cap is far inside i32"
+    )]
+    let n = n as i32;
+    Ok(n)
+}
+
+/// Service a call that reads guest memory and writes bytes back to it: the host
+/// fills the run's output buffer, which is copied to the guest once every rule has
+/// passed.
+///
+/// `call` gets the guest's whole memory, so it can borrow any number of input
+/// regions with [`Region::read`] — which a `&mut` view of that memory would forbid.
+/// That is why the answer goes through a buffer instead of straight into the guest
+/// as [`write_into`]'s does.
+///
+/// **The host is never told the guest's capacity**: it is offered the whole buffer
+/// and reports the value's true length, so the fit is decided here, with nothing yet
+/// in guest memory. A refused value therefore reaches it in no part.
+///
+/// The output is judged after the inputs, so a call with both bad reports the
+/// input's verdict. `NoMemExported` precedes both: there is no memory to validate a
+/// region against.
+pub(crate) fn write_buffered(
+    caller: &mut Caller<'_, VmState<'_>>,
+    out: Region,
+    call: impl FnOnce(&dyn HostFunctions, &[u8], &mut [u8]) -> HostResult<usize>,
+) -> CallResult<i32> {
+    let mem = memory(caller)?;
+    // One borrow split in two: the guest's bytes for the inputs, the store data for
+    // the output buffer. Taking them together is what keeps the inputs borrowed
+    // rather than copied out.
+    let (data, state) = mem.data_and_store_mut(&mut *caller);
+    let host: &dyn HostFunctions = state.host;
+
+    let n = call(host, data, &mut state.out_buffer[..])?;
+
+    // `out` is checked here rather than before the call: the inputs are judged
+    // first, so a call with both malformed reports the input's verdict.
+    let range = out.range()?;
+    let cap = range.len();
+    if n > MAX_FIELD_BYTES {
+        return Err(HostError::DataFieldTooLarge.into());
+    }
+    let buf = data.get_mut(range).ok_or(HostError::PointerOutOfBounds)?;
+    if n > cap {
+        return Err(HostError::BufferTooSmall.into());
+    }
+    charge_transfer(state, n)?;
+    buf[..n].copy_from_slice(&state.out_buffer[..n]);
+    #[expect(
+        clippy::cast_possible_truncation,
+        clippy::cast_possible_wrap,
+        reason = "`n > MAX_FIELD_BYTES` returned above, and the cap is far inside i32"
+    )]
+    let n = n as i32;
+    Ok(n)
+}
+
+/// The mantissa and exponent widths `float_to_mant_exp` writes: an `i64` and an `i32`.
+/// Fixed by the ABI, not the guest, so the split is a constant rather than a reported
+/// length.
+const MANTISSA_BYTES: usize = 8;
+const EXPONENT_BYTES: usize = 4;
+
+/// Service `float_to_mant_exp`, the one call that writes two output regions: the host
+/// fills the run's output buffer with the mantissa followed by the exponent, and each
+/// is copied to its own guest region once every rule has passed.
+///
+/// Like [`write_buffered`], the host reads its input from the guest's memory and writes
+/// to a scratch buffer, so the input stays borrowed rather than copied. The two output
+/// regions are judged after the input, and the mantissa's region before the exponent's,
+/// so the first fault reported is the leftmost.
+///
+/// The two widths are the ABI's rather than the guest's, so the length the host reports
+/// is checked against their sum for equality rather than as a bound, and ahead of the
+/// output regions: a wrong total means there is no answer to place, whatever the guest
+/// declared. That is a fatal error and not a status, since the guest asked for nothing
+/// wrong.
+pub(crate) fn write_mant_exp(
+    caller: &mut Caller<'_, VmState<'_>>,
+    mantissa_out: Region,
+    exponent_out: Region,
+    call: impl FnOnce(&dyn HostFunctions, &[u8], &mut [u8], &mut [u8]) -> HostResult<usize>,
+) -> CallResult<i32> {
+    let mem = memory(caller)?;
+    let (data, state) = mem.data_and_store_mut(&mut *caller);
+    let host: &dyn HostFunctions = state.host;
+
+    // The scratch buffer is split at the fixed mantissa width: the host fills the first
+    // eight bytes with the mantissa and the next four with the exponent.
+    let (mant_buf, exp_buf) = state.out_buffer.split_at_mut(MANTISSA_BYTES);
+    let mant_buf = &mut mant_buf[..MANTISSA_BYTES];
+    let exp_buf = &mut exp_buf[..EXPONENT_BYTES];
+
+    let total = call(host, data, mant_buf, exp_buf)?;
+
+    // Both buffers are fixed-width and were offered whole, so the only length the host
+    // can correctly report is their sum. Anything else is the host contradicting the
+    // ABI: with the widths in doubt, part of what would be copied out is whatever the
+    // previous call left in the buffer, so none of it is copied.
+    if total != MANTISSA_BYTES + EXPONENT_BYTES {
+        return Err(HostError::InternalFatal.into());
+    }
+
+    // Copy the mantissa, then the exponent, each only if its whole value fits its
+    // region — a region too small is `BufferTooSmall`, with nothing written.
+    let mant_range = mantissa_out.range()?;
+    let mant_dst = data
+        .get_mut(mant_range)
+        .ok_or(HostError::PointerOutOfBounds)?;
+    if mant_dst.len() < MANTISSA_BYTES {
+        return Err(HostError::BufferTooSmall.into());
+    }
+    mant_dst[..MANTISSA_BYTES].copy_from_slice(&state.out_buffer[..MANTISSA_BYTES]);
+
+    let exp_range = exponent_out.range()?;
+    let exp_dst = data
+        .get_mut(exp_range)
+        .ok_or(HostError::PointerOutOfBounds)?;
+    if exp_dst.len() < EXPONENT_BYTES {
+        return Err(HostError::BufferTooSmall.into());
+    }
+    exp_dst[..EXPONENT_BYTES]
+        .copy_from_slice(&state.out_buffer[MANTISSA_BYTES..MANTISSA_BYTES + EXPONENT_BYTES]);
+
+    charge_transfer(state, MANTISSA_BYTES + EXPONENT_BYTES)?;
+    #[expect(
+        clippy::cast_possible_truncation,
+        clippy::cast_possible_wrap,
+        reason = "a total other than 12 returned above, and 12 is far inside i32"
+    )]
+    let total = total as i32;
+    Ok(total)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::vm::TRANSFER_LIMIT_BYTES;
+    use std::cell::Cell;
+    use wasmi::StoreLimitsBuilder;
+    use xrpl_host_functions::TraceDataType;
+
+    /// `charge_transfer` takes the store data, which has to hold a host.
+    struct UncalledHost;
+
+    impl HostFunctions for UncalledHost {
+        fn get_ledger_sqn(&self, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_parent_ledger_time(&self, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_parent_ledger_hash(&self, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_base_fee(&self, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn is_amendment_enabled(&self, _amendment: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn cache_ledger_obj(&self, _obj_id: &[u8], _cache_idx: i32) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_tx_field(&self, _field: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_current_ledger_obj_field(&self, _field: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_ledger_obj_field(
+            &self,
+            _cache_idx: i32,
+            _field: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_tx_nested_field(&self, _locator: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_current_ledger_obj_nested_field(
+            &self,
+            _locator: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_ledger_obj_nested_field(
+            &self,
+            _cache_idx: i32,
+            _locator: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_tx_array_len(&self, _field: i32) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_current_ledger_obj_array_len(&self, _field: i32) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_ledger_obj_array_len(&self, _cache_idx: i32, _field: i32) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_tx_nested_array_len(&self, _locator: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_current_ledger_obj_nested_array_len(&self, _locator: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_ledger_obj_nested_array_len(
+            &self,
+            _cache_idx: i32,
+            _locator: &[u8],
+        ) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn check_signature(
+            &self,
+            _message: &[u8],
+            _signature: &[u8],
+            _pubkey: &[u8],
+        ) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn account_keylet(&self, _account: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn amm_keylet(&self, _asset1: &[u8], _asset2: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn check_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn credential_keylet(
+            &self,
+            _subject: &[u8],
+            _issuer: &[u8],
+            _credential_type: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn delegate_keylet(
+            &self,
+            _account: &[u8],
+            _authorize: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn deposit_preauth_keylet(
+            &self,
+            _account: &[u8],
+            _authorize: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn did_keylet(&self, _account: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn escrow_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn trust_line_keylet(
+            &self,
+            _account1: &[u8],
+            _account2: &[u8],
+            _currency: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn mptoken_issuance_keylet(
+            &self,
+            _issuer: &[u8],
+            _seq: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn mptoken_keylet(
+            &self,
+            _mptid: &[u8],
+            _holder: &[u8],
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn nftoken_offer_keylet(
+            &self,
+            _account: &[u8],
+            _seq: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn offer_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn oracle_keylet(
+            &self,
+            _account: &[u8],
+            _doc_id: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn paychannel_keylet(
+            &self,
+            _account: &[u8],
+            _destination: &[u8],
+            _seq: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn permissioned_domain_keylet(
+            &self,
+            _account: &[u8],
+            _seq: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn signer_list_keylet(&self, _account: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn ticket_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn vault_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn sha512_half(&self, _data: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn trace(&self, _msg: &str, _data: &[u8], _data_type: TraceDataType) -> HostResult<()> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn update_data(&self, _data: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft(&self, _account: &[u8], _nft_id: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_issuer(&self, _nft_id: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_taxon(&self, _nft_id: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_flags(&self, _nft_id: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_transfer_fee(&self, _nft_id: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn get_nft_sequence(&self, _nft_id: &[u8], _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_int(&self, _x: i64, _mode: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_uint(&self, _x: &[u8], _mode: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_stamount(
+            &self,
+            _amount: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_stnumber(
+            &self,
+            _number: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_to_int(&self, _x: &[u8], _mode: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_to_mant_exp(
+            &self,
+            _x: &[u8],
+            _mantissa_out: &mut [u8],
+            _exponent_out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_from_mant_exp(
+            &self,
+            _mantissa: i64,
+            _exponent: i32,
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_compare(&self, _x: &[u8], _y: &[u8]) -> HostResult<i32> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_add(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_subtract(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_multiply(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_divide(
+            &self,
+            _x: &[u8],
+            _y: &[u8],
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_root(&self, _x: &[u8], _n: i32, _mode: i32, _out: &mut [u8]) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+        fn float_power(
+            &self,
+            _x: &[u8],
+            _n: i32,
+            _mode: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
+    }
+
+    fn state(budget: u64) -> VmState<'static> {
+        VmState {
+            host: &UncalledHost,
+            mem_limits: StoreLimitsBuilder::new().build(),
+            transfer_budget: Cell::new(budget),
+            memory: None,
+            out_buffer: [0u8; MAX_FIELD_BYTES],
+        }
+    }
+
+    /// `wasmi::Error` is not `PartialEq`, so a test expecting the guest-visible
+    /// channel says so by going through here.
+    fn wire(result: CallResult<i32>) -> i32 {
+        to_wire(result)
+            .unwrap_or_else(|trap| panic!("expected a guest-visible status, got a trap: {trap}"))
+    }
+
+    #[test]
+    fn a_success_becomes_the_value_and_an_error_becomes_its_code() {
+        assert_eq!(wire(Ok(0)), 0);
+        assert_eq!(wire(Ok(32)), 32);
+        assert_eq!(wire(Err(HostError::BufferTooSmall.into())), -3);
+    }
+
+    /// The codes a host may answer that a contract must not see, and the fault each
+    /// becomes. Written out rather than derived from `From<HostError>`, which is what
+    /// they are asserting.
+    const STOPS_THE_RUN: [(HostError, Fault); 3] = [
+        (HostError::InternalFatal, Fault::Internal),
+        (HostError::Unimplemented, Fault::Internal),
+        (HostError::NoMemExported, Fault::NoMemory),
+    ];
+
+    /// Every fault, so the two tests below are the whole set and not a sample.
+    /// `From<Fault> for RunError` is what forces a fault added later to be
+    /// considered; this is what forces it to be tested.
+    const ALL_FAULTS: [Fault; 3] = [Fault::OutOfGas, Fault::Internal, Fault::NoMemory];
+
+    #[test]
+    fn a_code_that_stops_the_run_converts_to_its_fault() {
+        for (error, fault) in STOPS_THE_RUN {
+            assert_eq!(CallError::from(error), CallError::Fatal(fault), "{error:?}");
+        }
+    }
+
+    /// Over `HostError::ALL`, so it is the whole ABI and not a sample: a code added
+    /// to the ABI arrives already asserted to reach the guest as itself, and stopping
+    /// the run on it is then a change someone has to come and make.
+    ///
+    /// `OutOfTransferLimit` is the row worth reading twice: the one budget a
+    /// contract can be expected to handle, so it is told no rather than killed.
+    #[test]
+    fn every_other_code_reaches_the_guest_as_itself() {
+        for &error in HostError::ALL {
+            if STOPS_THE_RUN.iter().any(|&(stops, _)| stops == error) {
+                continue;
+            }
+            assert_eq!(CallError::from(error), CallError::Code(error), "{error:?}");
+            assert_eq!(wire(Err(error.into())), error.code(), "{error:?}");
+        }
+    }
+
+    /// The trap carries the fault, so `run` can name the outcome without parsing a
+    /// message.
+    #[test]
+    fn a_fault_becomes_a_trap_carrying_it() {
+        for fault in ALL_FAULTS {
+            let trap = to_wire(Err(CallError::Fatal(fault)))
+                .expect_err("a fault must not reach the guest as a code");
+            let payload = trap.downcast_ref::<FatalHostError>().unwrap_or_else(|| {
+                panic!("{fault:?}: expected a FatalHostError payload, got: {trap}")
+            });
+            assert_eq!(*payload, FatalHostError(fault));
+        }
+    }
+
+    /// The result-less path splits the same two channels differently: a fault still
+    /// stops the run, and every code is dropped, since `trace` has no return value to
+    /// carry it. Over `HostError::ALL` for the reason above — a code added to the ABI
+    /// arrives asserted against both paths.
+    #[test]
+    fn a_call_with_no_result_drops_a_code_and_traps_on_a_fault() {
+        assert!(dropped(Ok(())).is_ok());
+
+        for &error in HostError::ALL {
+            if let CallError::Code(code) = CallError::from(error) {
+                assert!(
+                    dropped(Err(CallError::Code(code))).is_ok(),
+                    "{error:?} has no channel to the guest and must be dropped"
+                );
+            }
+        }
+
+        for fault in ALL_FAULTS {
+            let trap =
+                dropped(Err(CallError::Fatal(fault))).expect_err("a fault must stop the run");
+            let payload = trap.downcast_ref::<FatalHostError>().unwrap_or_else(|| {
+                panic!("{fault:?}: expected a FatalHostError payload, got: {trap}")
+            });
+            assert_eq!(*payload, FatalHostError(fault));
+        }
+    }
+
+    #[test]
+    fn a_transfer_spends_the_budget() {
+        let state = state(100);
+
+        assert_eq!(charge_transfer(&state, 30), Ok(()));
+        assert_eq!(state.transfer_budget.get(), 70);
+        assert_eq!(charge_transfer(&state, 70), Ok(()));
+        assert_eq!(state.transfer_budget.get(), 0);
+    }
+
+    /// The budget bounds the total, so the transfer that would overrun it is
+    /// refused whole rather than partially charged.
+    #[test]
+    fn a_transfer_past_the_budget_is_refused_and_charges_nothing() {
+        let state = state(100);
+
+        assert_eq!(
+            charge_transfer(&state, 101),
+            Err(HostError::OutOfTransferLimit)
+        );
+        assert_eq!(
+            state.transfer_budget.get(),
+            100,
+            "a refusal must not charge"
+        );
+        assert_eq!(charge_transfer(&state, 100), Ok(()));
+        assert_eq!(
+            charge_transfer(&state, 1),
+            Err(HostError::OutOfTransferLimit)
+        );
+    }
+
+    #[test]
+    fn transferring_nothing_costs_nothing() {
+        let state = state(0);
+
+        assert_eq!(charge_transfer(&state, 0), Ok(()));
+        assert_eq!(state.transfer_budget.get(), 0);
+    }
+
+    /// The field cap holds one call to a small share of the run's budget, so the
+    /// budget bounds a run rather than a call. An inequality, not the two values:
+    /// those are pinned in `vm.rs`.
+    #[test]
+    fn no_single_value_can_exhaust_the_run_budget() {
+        assert!(
+            (MAX_FIELD_BYTES as u64) * 64 <= TRANSFER_LIMIT_BYTES,
+            "one {MAX_FIELD_BYTES}-byte value against a {TRANSFER_LIMIT_BYTES}-byte budget"
+        );
+    }
+}

crates/xrpl-wasm-vm/src/lib.rs

@@ -0,0 +1,28 @@
+//! The escrow wasm VM: compile a contract, meter it, and serve its host calls.
+//!
+//! Every guest access goes through `abi.rs` and reaches linear memory only by
+//! wasmi's bounds-checked slice operations; `forbid(unsafe_code)` makes that a
+//! property rather than a claim. The cast lints are on for the same reason — on a
+//! consensus path a truncating or sign-losing cast changes what a contract is
+//! charged or told, so each one is argued for at its site.
+#![forbid(unsafe_code)]
+#![deny(rustdoc::broken_intra_doc_links)]
+#![deny(unreachable_pub)]
+#![deny(
+    clippy::cast_possible_truncation,
+    clippy::cast_possible_wrap,
+    clippy::cast_sign_loss,
+    clippy::cast_lossless
+)]
+
+mod abi;
+mod preflight;
+mod region;
+mod register;
+mod vm;
+
+pub use preflight::{CheckError, check};
+pub use vm::{
+    MAX_FIELD_BYTES, MAX_MEMORY_BYTES, MAX_MEMORY_PAGES, RunError, RunFailure, RunOutcome,
+    TRANSFER_LIMIT_BYTES, run,
+};

crates/xrpl-wasm-vm/src/preflight.rs

@@ -0,0 +1,351 @@
+//! Screening a contract before it reaches the ledger.
+//!
+//! [`check`] answers whether [`crate::run`] would refuse a module before the
+//! guest's first instruction — the three stages a caller maps to a malformed
+//! transaction rather than to a failed one. It needs **no host, no store and no
+//! gas**: everything it reads is a property of the compiled module. That is what
+//! makes it callable from a transaction's preflight, which has no ledger to serve
+//! host calls from.
+//!
+//! Two things it deliberately does not screen. A module exporting **no** linear
+//! memory passes: a contract that makes no host call needs none, and one that
+//! does is refused at the call and charged for what it burned. A start section
+//! passes: it is guest code, and executing it is the one thing a check must not do
+//! — a trap in one is charged to the contract like any other trap.
+//!
+//! One thing it screens that a run can only discover: an exported memory larger
+//! than the engine grants. See [`check_memory`] for what stays invisible.
+
+use std::fmt;
+use wasmi::{ExternType, FuncType, Module, ValType};
+use xrpl_host_functions::HostFunctionSpec;
+
+use crate::register::HOST_MODULE;
+use crate::vm::{MAX_MEMORY_PAGES, compile};
+
+/// Why a module cannot be run. One variant per stage, since the caller maps the
+/// stages separately.
+#[derive(Debug)]
+pub enum CheckError {
+    /// `wasm` is not a valid module under this engine's configuration.
+    Compile(String),
+    /// An import no engine of this ABI defines: another module namespace, a name
+    /// that is not a host function, or one imported as something other than a
+    /// function.
+    Import(String),
+    /// No export named `function_name` with signature `() -> i32`.
+    EntryPoint(String),
+    /// The module asks for more linear memory than the engine grants.
+    Memory(String),
+}
+
+impl fmt::Display for CheckError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            CheckError::Compile(detail) => write!(f, "compile: {detail}"),
+            CheckError::Import(detail) => write!(f, "import: {detail}"),
+            // The detail says which of the entry point's failures this is, since
+            // "no entry point" would be wrong for an export of the wrong type.
+            CheckError::EntryPoint(detail) => write!(f, "{detail}"),
+            CheckError::Memory(detail) => write!(f, "memory: {detail}"),
+        }
+    }
+}
+
+/// Screen `wasm`: it must compile, import only what the engine serves, export
+/// `function_name` as `() -> i32`, and ask for no more memory than it may have.
+///
+/// The stages are ordered by how much of the module each explains. An import fault
+/// is reported before a missing entry point because the imports are what the rest of
+/// the module is built on; memory comes last, being a resource request rather than a
+/// mistake about the ABI.
+pub fn check(wasm: &[u8], function_name: &str) -> Result<(), CheckError> {
+    let module = compile(wasm).map_err(CheckError::Compile)?;
+    check_imports(&module)?;
+    check_entry_point(&module, function_name)?;
+    check_memory(&module)
+}
+
+/// Every import must be one the linker defines. The first that is not ends the
+/// check, so a module with several faults reports the earliest.
+fn check_imports(module: &Module) -> Result<(), CheckError> {
+    for import in module.imports() {
+        check_import(import.module(), import.name(), import.ty()).map_err(CheckError::Import)?;
+    }
+    Ok(())
+}
+
+/// Whether the engine defines this one import.
+///
+/// The set of names is [`HostFunctionSpec::ALL`], which is also what
+/// [`crate::register::register_host_functions`] iterates — so a check and a run
+/// cannot disagree about which names exist, and adding a host function extends
+/// both at once. The one thing this does not compare is `ty`'s *signature*, which
+/// still parts a module from the engine at instantiation; the kind is compared
+/// because the engine defines these names as functions and as nothing else.
+///
+/// The rules are ordered, not merely alternatives: a guest importing `env::malloc`
+/// is told about the namespace rather than that `malloc` is not a host function,
+/// because the namespace is the one that explains every other import it has too.
+fn check_import(module: &str, name: &str, ty: &ExternType) -> Result<(), String> {
+    if module != HOST_MODULE {
+        return Err(format!("'{module}::{name}' is not from '{HOST_MODULE}'"));
+    }
+    if !HostFunctionSpec::ALL
+        .iter()
+        .any(|op| op.wasm_name() == name)
+    {
+        return Err(format!("no host function '{name}'"));
+    }
+    if !matches!(ty, ExternType::Func(_)) {
+        return Err(format!("'{HOST_MODULE}::{name}' is not a function"));
+    }
+    Ok(())
+}
+
+fn check_entry_point(module: &Module, name: &str) -> Result<(), CheckError> {
+    match module.get_export(name) {
+        Some(ExternType::Func(ty)) if is_entry_point(&ty) => Ok(()),
+        found => Err(CheckError::EntryPoint(entry_point_fault(found, name))),
+    }
+}
+
+/// The entry point's type: nothing in, one `i32` out — what [`crate::run`]'s
+/// `get_typed_func::<(), i32>` accepts.
+fn is_entry_point(ty: &FuncType) -> bool {
+    ty.params().is_empty() && matches!(ty.results(), [ValType::I32])
+}
+
+/// A module may not declare more linear memory than the engine grants.
+///
+/// Only what it *exports* is visible here. A memory a module keeps to itself is not
+/// in its exports, and the store's limiter is what refuses that one — at
+/// instantiation, where the run is charged nothing and the caller cannot tell it
+/// from any other resource failure. Screening the exported case covers every
+/// contract built against the guest SDK, since a contract needs an exported memory
+/// to make a host call at all.
+fn check_memory(module: &Module) -> Result<(), CheckError> {
+    for export in module.exports() {
+        if let ExternType::Memory(ty) = export.ty() {
+            check_initial_pages(ty.minimum()).map_err(CheckError::Memory)?;
+        }
+    }
+    Ok(())
+}
+
+/// Whether the engine will grant a memory of this declared initial size.
+///
+/// The *minimum* only: a declared maximum past the cap is legal and simply
+/// unreachable, which `vm_limits::a_declared_maximum_past_the_cap_is_allowed_but_
+/// unreachable` pins on the run side. Refusing it here would turn a runnable
+/// contract away.
+fn check_initial_pages(pages: u64) -> Result<(), String> {
+    if pages > u64::from(MAX_MEMORY_PAGES) {
+        return Err(format!(
+            "initial memory of {pages} pages is past the {MAX_MEMORY_PAGES}-page cap"
+        ));
+    }
+    Ok(())
+}
+
+/// How an entry-point lookup failed, in the words both stages use: a check and a
+/// run describe the same module the same way, and "no entry point" would send a
+/// contract author looking for a function they already have.
+pub(crate) fn entry_point_fault(found: Option<ExternType>, name: &str) -> String {
+    match found {
+        Some(ExternType::Func(_)) => {
+            format!("entry point '{name}' has the wrong signature, expected '() -> i32'")
+        }
+        Some(_) => format!("export '{name}' is not a function"),
+        None => format!("no entry point '{name}'"),
+    }
+}
+
+/// The rules, one by one, on inputs built directly rather than parsed out of a
+/// module. `tests/preflight.rs` runs real modules through [`check`]; what is here is
+/// what a module cannot state precisely — which rule fires, in which order, and in
+/// what words the caller logs it.
+///
+/// `wat` is a dev-dependency, so the one test here that does need a module writes it
+/// as text like every other test in the crate. What the library must not gain is a
+/// text *entry point* — `check` and `run` take binaries — and a `cfg(test)` caller
+/// cannot give it one.
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use wasmi::{GlobalType, MemoryType, Mutability};
+
+    /// A host function as a guest declares it. Any function type will do: the
+    /// signature is not what [`check_import`] compares.
+    fn a_function() -> ExternType {
+        ExternType::Func(FuncType::new([ValType::I32], [ValType::I32]))
+    }
+
+    /// A name every one of these tests can use, taken from the ABI rather than
+    /// spelled, so it stays a real host function as the ABI changes.
+    fn a_host_function_name() -> &'static str {
+        HostFunctionSpec::ALL[0].wasm_name()
+    }
+
+    // -----------------------------------------------------------------------
+    // Imports
+    // -----------------------------------------------------------------------
+
+    /// Every name the ABI declares is served. Derived from `ALL` rather than
+    /// listed, so a host function added to the ABI is covered the day it lands.
+    #[test]
+    fn every_declared_host_function_is_served() {
+        for op in HostFunctionSpec::ALL {
+            assert_eq!(
+                check_import(HOST_MODULE, op.wasm_name(), &a_function()),
+                Ok(()),
+                "{}",
+                op.wasm_name()
+            );
+        }
+    }
+
+    #[test]
+    fn an_import_from_another_namespace_is_refused() {
+        for namespace in ["env", "host", "host_lib2", ""] {
+            let refusal = check_import(namespace, a_host_function_name(), &a_function())
+                .expect_err(namespace);
+            assert!(
+                refusal.contains("is not from 'host_lib'"),
+                "{namespace}: {refusal}"
+            );
+        }
+    }
+
+    #[test]
+    fn an_unknown_name_is_refused() {
+        let refusal =
+            check_import(HOST_MODULE, "no_such_function", &a_function()).expect_err("unknown name");
+        assert_eq!(refusal, "no host function 'no_such_function'");
+    }
+
+    /// The engine defines these names as functions and as nothing else, so a module
+    /// importing one as a global or a memory does not link either.
+    #[test]
+    fn a_host_function_imported_as_anything_else_is_refused() {
+        for ty in [
+            ExternType::Global(GlobalType::new(ValType::I32, Mutability::Const)),
+            ExternType::Memory(MemoryType::new(1, None)),
+        ] {
+            let name = a_host_function_name();
+            let refusal = check_import(HOST_MODULE, name, &ty).expect_err("not a function");
+            assert_eq!(refusal, format!("'host_lib::{name}' is not a function"));
+        }
+    }
+
+    /// The rules are ordered. An import that breaks two of them is reported by the
+    /// first, so the message a contract author reads is the one that explains the
+    /// rest of their imports too.
+    #[test]
+    fn the_namespace_is_reported_before_the_name() {
+        let refusal = check_import("env", "no_such_function", &a_function())
+            .expect_err("neither the namespace nor the name is served");
+
+        assert!(refusal.contains("is not from 'host_lib'"), "{refusal}");
+        assert!(
+            !refusal.contains("no host function"),
+            "the namespace explains it: {refusal}"
+        );
+    }
+
+    /// Both halves of the type are load-bearing, and neither is checked anywhere
+    /// a module cannot reach.
+    #[test]
+    fn the_entry_point_type_is_nothing_in_and_one_i32_out() {
+        assert!(is_entry_point(&FuncType::new([], [ValType::I32])));
+
+        for wrong in [
+            FuncType::new([], []),
+            FuncType::new([], [ValType::I64]),
+            FuncType::new([ValType::I32], [ValType::I32]),
+            FuncType::new([], [ValType::I32, ValType::I32]),
+        ] {
+            assert!(!is_entry_point(&wrong), "{wrong:?}");
+        }
+    }
+
+    /// Three faults, three descriptions. A run reports these too, with wasmi's own
+    /// error appended, so a swapped arm would mislead at both stages at once.
+    #[test]
+    fn each_entry_point_fault_is_described_as_itself() {
+        assert_eq!(
+            entry_point_fault(Some(a_function()), "finish"),
+            "entry point 'finish' has the wrong signature, expected '() -> i32'"
+        );
+        assert_eq!(
+            entry_point_fault(
+                Some(ExternType::Global(GlobalType::new(
+                    ValType::I32,
+                    Mutability::Const
+                ))),
+                "finish"
+            ),
+            "export 'finish' is not a function"
+        );
+        assert_eq!(
+            entry_point_fault(None, "finish"),
+            "no entry point 'finish'",
+            "an absent export must not be reported as a wrong signature"
+        );
+    }
+
+    /// The cap itself is granted; one page past it is not. The boundary is the whole
+    /// rule, and it is the same boundary the store's limiter applies at
+    /// instantiation.
+    #[test]
+    fn the_initial_memory_may_reach_the_cap_but_not_pass_it() {
+        assert_eq!(check_initial_pages(0), Ok(()));
+        assert_eq!(check_initial_pages(u64::from(MAX_MEMORY_PAGES)), Ok(()));
+
+        let past = u64::from(MAX_MEMORY_PAGES) + 1;
+        let refusal = check_initial_pages(past).expect_err("one page past the cap");
+        assert_eq!(
+            refusal,
+            format!("initial memory of {past} pages is past the {MAX_MEMORY_PAGES}-page cap")
+        );
+    }
+
+    /// The bridge logs this string and the C++ tests match on it, so the stage's
+    /// prefix is part of the interface rather than a debugging aid.
+    #[test]
+    fn a_refusal_names_its_stage() {
+        assert_eq!(
+            CheckError::Compile("bad magic".to_string()).to_string(),
+            "compile: bad magic"
+        );
+        assert_eq!(
+            CheckError::Memory("initial memory of 129 pages".to_string()).to_string(),
+            "memory: initial memory of 129 pages"
+        );
+        assert_eq!(
+            CheckError::Import("no host function 'x'".to_string()).to_string(),
+            "import: no host function 'x'"
+        );
+        // The entry point's detail already says which of its three faults it is,
+        // so a prefix would only repeat it.
+        assert_eq!(
+            CheckError::EntryPoint("no entry point 'finish'".to_string()).to_string(),
+            "no entry point 'finish'"
+        );
+    }
+
+    #[test]
+    fn the_stages_run_in_order() {
+        assert!(
+            matches!(check(b"not wasm", "finish"), Err(CheckError::Compile(_))),
+            "nothing is screened until the module compiles"
+        );
+
+        // A module that compiles and imports nothing, so it reaches the entry point.
+        let empty = wat::parse_str("(module)").expect("assembles");
+        assert!(
+            matches!(check(&empty, "finish"), Err(CheckError::EntryPoint(_))),
+            "a module that compiles and imports nothing reaches the entry point"
+        );
+    }
+}

crates/xrpl-wasm-vm/src/region.rs

@@ -0,0 +1,50 @@
+use crate::vm::MAX_FIELD_BYTES;
+use core::ops::Range;
+use xrpl_host_functions::{HostError, HostResult};
+
+/// A byte region as the guest declared it: the `(ptr, len)` pair off the wire, not
+/// yet checked.
+///
+/// Every byte parameter in this ABI is such a pair, so pairing them once at the wire
+/// boundary is what keeps the helpers in `abi.rs` from each taking two loose integers
+/// they could be handed in either order.
+///
+/// It lives in a module of its own so that the fields are out of reach and
+/// [`range`](Region::range) is the *only* way to indices — the check cannot be
+/// skipped, only deferred. Construction is infallible for that reason: a call whose
+/// output region is malformed is then refused in the order its own helper chooses,
+/// rather than at the moment the pair happened to be formed.
+#[derive(Copy, Clone)]
+pub(crate) struct Region {
+    ptr: i32,
+    len: i32,
+}
+
+impl Region {
+    pub(crate) fn new(ptr: i32, len: i32) -> Region {
+        Region { ptr, len }
+    }
+
+    /// `start..end` as indices. The conversion is the negativity check — it fails on
+    /// exactly the negative values — and the addition guards a 32-bit `usize`, where
+    /// two `i32`s can sum past the end.
+    pub(crate) fn range(self) -> HostResult<Range<usize>> {
+        let (Ok(start), Ok(len)) = (usize::try_from(self.ptr), usize::try_from(self.len)) else {
+            return Err(HostError::InvalidParams);
+        };
+        let end = start
+            .checked_add(len)
+            .ok_or(HostError::PointerOutOfBounds)?;
+        Ok(start..end)
+    }
+
+    /// The region's bytes, refused past the field cap. No copy: the slice aliases
+    /// `data`.
+    pub(crate) fn read(self, data: &[u8]) -> HostResult<&[u8]> {
+        let range = self.range()?;
+        if range.len() > MAX_FIELD_BYTES {
+            return Err(HostError::DataFieldTooLarge);
+        }
+        data.get(range).ok_or(HostError::PointerOutOfBounds)
+    }
+}

crates/xrpl-wasm-vm/src/vm.rs

@@ -0,0 +1,353 @@
+use std::cell::Cell;
+use std::fmt;
+use std::sync::LazyLock;
+use wasmi::{
+    Config, Engine, Export, Linker, Memory, Module, Store, StoreLimits, StoreLimitsBuilder,
+    TrapCode,
+};
+use xrpl_host_functions::HostFunctions;
+
+use crate::abi::{FatalHostError, Fault};
+use crate::preflight::entry_point_fault;
+use crate::register::register_host_functions;
+
+/// wasm linear-memory page size, fixed by the wasm spec (64 KiB).
+const WASM_PAGE_BYTES: u32 = 64 * 1024;
+
+/// Linear-memory page cap.
+pub const MAX_MEMORY_PAGES: u32 = 128;
+
+/// [`MAX_MEMORY_PAGES`] in bytes: 8 MiB.
+pub const MAX_MEMORY_BYTES: usize = (MAX_MEMORY_PAGES * WASM_PAGE_BYTES) as usize;
+
+/// Total bytes that may cross the host/guest boundary in one [`run`], separate
+/// from gas.
+pub const TRANSFER_LIMIT_BYTES: u64 = 1 << 20;
+
+/// Size cap on any single value crossing the boundary, in either direction; over
+/// it is `DataFieldTooLarge`.
+///
+/// A protocol limit: `kMaxWasmDataLength` in `include/xrpl/protocol/Protocol.h`.
+pub const MAX_FIELD_BYTES: usize = 1024;
+
+/// State threaded through every host call, stored in the wasmi [`Store`].
+pub(crate) struct VmState<'h> {
+    pub(crate) host: &'h dyn HostFunctions,
+    /// Enforces [`MAX_MEMORY_BYTES`] via `Store::limiter`, which needs a `&mut`
+    /// into it from `&mut VmState` — hence a field rather than a local.
+    pub(crate) mem_limits: StoreLimits,
+    /// Remaining transfer budget for this run ([`TRANSFER_LIMIT_BYTES`]).
+    ///
+    /// A `Cell` because it is decremented from a shared `&Caller`. One thread per
+    /// invocation touches the store, so the lack of `Sync` costs nothing.
+    ///
+    /// TODO: the extra charge for an unaligned field copy has nothing to attach to
+    /// until this ABI gains a `FieldLocator` host function.
+    pub(crate) transfer_budget: Cell<u64>,
+    /// The guest's linear memory, resolved once by [`run`] after instantiation so
+    /// no host call pays for an export lookup.
+    ///
+    /// Caching the handle is sound because a [`Memory`] is an arena index, not a
+    /// pointer to the bytes: it survives `memory.grow`, and `data`/`data_mut`
+    /// re-derive the slice per call.
+    ///
+    /// The handle is scoped to one store, so this assumes **one module, one
+    /// instance, one store per `run`**. Module linking or nested execution would
+    /// have to resolve per instance: a cached handle would serve a call against the
+    /// wrong instance's memory, which is a wrong answer rather than an error.
+    pub(crate) memory: Option<Memory>,
+    /// Where a host writes a value before [`crate::abi::write_buffered`] copies it
+    /// to the guest. One buffer per run, so no call zero-fills one of its own.
+    ///
+    /// Inline rather than boxed: the store's data is built once and then only
+    /// borrowed, so a kilobyte in it costs a move where a `Box` costs an
+    /// allocation. A local would cost neither, but `forbid(unsafe_code)` means a
+    /// stack buffer is zero-filled — per call, which is the cost this removes.
+    pub(crate) out_buffer: [u8; MAX_FIELD_BYTES],
+}
+
+/// Outcome of running an escrow contract to completion.
+#[derive(Debug)]
+pub struct RunOutcome {
+    /// The value returned by the exported entry point (`finish`): `> 0` means
+    /// allow the escrow to finish.
+    pub result: i32,
+    /// Fuel (gas) consumed by the whole invocation — guest instructions plus
+    /// the per-call host charges.
+    pub fuel_used: u64,
+}
+
+/// Why a run produced no result. Each variant is one outcome for the caller to
+/// map to a TER.
+#[derive(Debug)]
+pub enum RunError {
+    /// `wasm` is not a valid module under this engine's configuration.
+    Compile(String),
+    /// The module compiled but the engine would not accept it: an import the
+    /// linker does not define, or an initial memory past the page cap. Not guest
+    /// code failing — a start section that traps is [`RunError::Trap`].
+    Instantiate(String),
+    /// No export named `function_name` with signature `() -> i32`: absent, not a
+    /// function, or a function of another type — which the detail tells apart.
+    EntryPoint(String),
+    /// Gas exhausted — by the guest's own instructions or by a host call's
+    /// charge. [`RunFailure::fuel_used`] is the whole limit.
+    OutOfGas,
+    /// The host could not serve a call.
+    Internal,
+    /// A host call had no linear memory to work in: the module exports none, or
+    /// the call came from a start section, which runs before there is an instance
+    /// to resolve the memory from.
+    NoMemory,
+    /// The guest trapped: `unreachable`, division by zero, an out-of-bounds
+    /// access, or `memory.grow` past the page cap. Wherever the guest was
+    /// executing, including a start section during instantiation.
+    Trap(String),
+}
+
+impl fmt::Display for RunError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            RunError::Compile(detail) => write!(f, "compile: {detail}"),
+            RunError::Instantiate(detail) => write!(f, "instantiate: {detail}"),
+            // The detail says which of the entry point's failures this is, since
+            // "no entry point" would be wrong for an export of the wrong type.
+            RunError::EntryPoint(detail) => write!(f, "{detail}"),
+            RunError::OutOfGas => write!(f, "out of gas"),
+            RunError::Internal => write!(f, "internal error"),
+            RunError::NoMemory => write!(f, "no exported memory"),
+            RunError::Trap(detail) => write!(f, "trap: {detail}"),
+        }
+    }
+}
+
+/// A failed run, with the gas it still owes: a contract that traps or exhausts
+/// its gas is charged for what it burned.
+#[derive(Debug)]
+pub struct RunFailure {
+    pub error: RunError,
+    /// Fuel consumed before the failure. The whole limit when gas ran out; `0`
+    /// when the module never ran.
+    pub fuel_used: u64,
+}
+
+impl fmt::Display for RunFailure {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{} (fuel used: {})", self.error, self.fuel_used)
+    }
+}
+
+impl RunFailure {
+    /// A failure with no fuel accounted: it stopped the run at or before the guest's
+    /// first instruction, or under a store with no meter to read.
+    fn owing_nothing(error: RunError) -> RunFailure {
+        RunFailure {
+            error,
+            fuel_used: 0,
+        }
+    }
+}
+
+/// Fuel spent out of `gas`: the one place a run's cost is measured, so success,
+/// trap and refusal all report it the same way.
+///
+/// `Store::get_fuel` fails only on a store without fuel metering, which
+/// [`build_wasm_engine`] rules out and `run`'s `set_fuel` would already have
+/// caught — so a failure here is a defect in this crate. It must not become a
+/// number: `0` forgives a run its whole cost, `gas` charges an untouched one for
+/// everything. [`RunError::Internal`] instead.
+fn fuel_used(store: &Store<VmState<'_>>, gas: u64) -> Result<u64, RunError> {
+    store
+        .get_fuel()
+        .map(|remaining| gas.saturating_sub(remaining))
+        .map_err(|_| RunError::Internal)
+}
+
+/// Report `error` with the run's cost attached. A cost that cannot be read replaces
+/// the outcome rather than being invented — see [`fuel_used`].
+fn failed(store: &Store<VmState<'_>>, gas: u64, error: RunError) -> RunFailure {
+    match fuel_used(store, gas) {
+        Ok(fuel_used) => RunFailure { error, fuel_used },
+        Err(unmetered) => RunFailure::owing_nothing(unmetered),
+    }
+}
+
+/// The outcome a `wasmi::Error` names for itself, if any, rather than leaving it to
+/// the stage that raised it.
+///
+/// Two ways a run halts mid-flight: a host call that could not be served, which
+/// carries a [`FatalHostError`] saying which condition it was, and the guest's own
+/// instructions exhausting the meter, which wasmi raises as `OutOfFuel`.
+///
+/// Both can happen anywhere the guest executes — including a start section, which
+/// is guest code running during instantiation — so every stage from there on asks
+/// this before naming a failure after itself.
+fn guest_halted(error: &wasmi::Error) -> Option<RunError> {
+    if let Some(fatal) = error.downcast_ref::<FatalHostError>() {
+        return Some(fatal.0.into());
+    }
+    (error.as_trap_code() == Some(TrapCode::OutOfFuel)).then_some(RunError::OutOfGas)
+}
+
+/// Why instantiation failed, once [`guest_halted`] has ruled out the two conditions
+/// that can arise anywhere.
+///
+/// A start section is guest code, so it can trap on its own — `unreachable`, a
+/// division by zero, an out-of-bounds access — and a trap is the guest's fault
+/// wherever it happens. Naming that after the *stage* would file it beside the
+/// module faults a caller treats as its own defect, and charge nothing for
+/// instructions the contract burned. What is left for [`RunError::Instantiate`] is a
+/// module the linker or the store would not accept at all.
+fn instantiation_failure(error: &wasmi::Error) -> RunError {
+    match error.as_trap_code() {
+        Some(_) => RunError::Trap(error.to_string()),
+        None => RunError::Instantiate(error.to_string()),
+    }
+}
+
+/// The outcome a [`Fault`] is: the one place a stopped call becomes a stopped run.
+///
+/// Total and one arm each, because a `Fault` is only ever a condition that stops the
+/// run — the guest-visible codes cannot reach here, which is what
+/// [`crate::abi::CallError`] buys. A fault added later has no arm and does not
+/// compile.
+impl From<Fault> for RunError {
+    fn from(fault: Fault) -> RunError {
+        match fault {
+            Fault::OutOfGas => RunError::OutOfGas,
+            Fault::Internal => RunError::Internal,
+            Fault::NoMemory => RunError::NoMemory,
+        }
+    }
+}
+
+/// The process-wide wasmi engine, built once on first use.
+///
+/// The configuration is consensus-fixed and identical for every invocation, and an
+/// [`Engine`] is an internally `Arc`ed `Send + Sync` handle, so one shared engine
+/// serves concurrent [`run`] calls.
+pub(crate) fn wasm_engine() -> &'static Engine {
+    static ENGINE: LazyLock<Engine> = LazyLock::new(build_wasm_engine);
+    &ENGINE
+}
+
+/// Build the wasmi engine the escrow VM requires: deterministic, minimal
+/// features, fuel metering on.
+fn build_wasm_engine() -> Engine {
+    let mut config = Config::default();
+    config.consume_fuel(true);
+    config.ignore_custom_sections(true);
+    config.wasm_mutable_global(false);
+    config.wasm_multi_value(false);
+    config.wasm_sign_extension(false);
+    config.wasm_saturating_float_to_int(false);
+    config.wasm_bulk_memory(false);
+    config.wasm_reference_types(false);
+    config.wasm_tail_call(false);
+    config.wasm_extended_const(false);
+    config.floats(false);
+    config.wasm_multi_memory(false);
+    config.wasm_custom_page_sizes(false);
+    config.wasm_memory64(false);
+    config.wasm_wide_arithmetic(false);
+    // TODO: enable option to reject wasm code containing start section after wasmi 2.0 release
+    Engine::new(&config)
+}
+
+/// Compile `wasm` for this engine.
+///
+/// The one path to a [`Module`]: the configuration is what decides whether a
+/// contract is valid at all, so [`run`] and [`crate::check`] must not be able to
+/// compile against different ones.
+pub(crate) fn compile(wasm: &[u8]) -> Result<Module, String> {
+    Module::new(wasm_engine(), wasm).map_err(|e| e.to_string())
+}
+
+/// Run a contract: compile `wasm`, give it `gas` fuel, service its host
+/// calls through `host`, and call the exported `function_name`.
+pub fn run<'h>(
+    wasm: &[u8],
+    gas: u64,
+    host: &'h dyn HostFunctions,
+    function_name: &str,
+) -> Result<RunOutcome, RunFailure> {
+    let engine = wasm_engine();
+    let module =
+        compile(wasm).map_err(|detail| RunFailure::owing_nothing(RunError::Compile(detail)))?;
+
+    let mem_limits = StoreLimitsBuilder::new()
+        .memory_size(MAX_MEMORY_BYTES)
+        .trap_on_grow_failure(true)
+        .build();
+    let mut store = Store::new(
+        engine,
+        VmState {
+            host,
+            mem_limits,
+            transfer_budget: Cell::new(TRANSFER_LIMIT_BYTES),
+            memory: None,
+            out_buffer: [0u8; MAX_FIELD_BYTES],
+        },
+    );
+
+    store
+        .set_fuel(gas)
+        .map_err(|_| RunFailure::owing_nothing(RunError::Internal))?;
+    store.limiter(|state| &mut state.mem_limits);
+
+    let mut linker = Linker::<VmState<'h>>::new(engine);
+    register_host_functions(&mut linker)
+        .map_err(|_| RunFailure::owing_nothing(RunError::Internal))?;
+
+    let instance = match linker.instantiate_and_start(&mut store, &module) {
+        Ok(instance) => instance,
+        Err(e) => {
+            let error = guest_halted(&e).unwrap_or_else(|| instantiation_failure(&e));
+            return Err(failed(&store, gas, error));
+        }
+    };
+    store.data_mut().memory = instance.exports(&store).find_map(Export::into_memory);
+
+    let function = match instance.get_typed_func::<(), i32>(&store, function_name) {
+        Ok(function) => function,
+        Err(e) => {
+            let found = instance
+                .get_export(&store, function_name)
+                .map(|export| export.ty(&store));
+            let error =
+                RunError::EntryPoint(format!("{}: {e}", entry_point_fault(found, function_name)));
+            return Err(failed(&store, gas, error));
+        }
+    };
+
+    let result = match function.call(&mut store, ()) {
+        Ok(result) => result,
+        Err(e) => {
+            let error = guest_halted(&e).unwrap_or_else(|| RunError::Trap(e.to_string()));
+            return Err(failed(&store, gas, error));
+        }
+    };
+
+    let fuel_used = fuel_used(&store, gas).map_err(RunFailure::owing_nothing)?;
+    Ok(RunOutcome { result, fuel_used })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_engine_is_one_engine() {
+        assert!(Engine::same(wasm_engine(), wasm_engine()));
+    }
+
+    /// The only place these numbers appear as literals; every other test derives
+    /// them from the constants.
+    #[test]
+    fn the_limits_are_the_protocol_limits() {
+        assert_eq!(MAX_MEMORY_PAGES, 128, "linear-memory page cap");
+        assert_eq!(MAX_MEMORY_BYTES, 8 * 1024 * 1024, "page cap in bytes");
+        assert_eq!(MAX_FIELD_BYTES, 1024, "kMaxWasmDataLength");
+        assert_eq!(TRANSFER_LIMIT_BYTES, 1 << 20, "kWasmTransferLimit");
+    }
+}