refactor(telemetry): mark the span factories and trace-context checks nodiscard

The trace-context checks validate bytes received from a peer, so a
discarded result means untrusted input was accepted unchecked. hashSpan(),
txReceiveSpan() and txProcessSpan() return an RAII guard; discarding one ends
the span on the same line it began.

The telemetry-disabled twins of both hashSpan overloads already carried the
attribute, so the two #ifdef arms now agree. Both hashSpan overloads also
gain the @return line their siblings already had, now that the result cannot
be dropped.

No caller in the chain discards any of these results.

include/xrpl/telemetry/SpanGuard.h

@@ -394,8 +394,10 @@ public:
      * @param name      Full span name (e.g. "tx.receive").
      * @param hashData  Pointer to at least 16 bytes of hash data.
      * @param hashSize  Size of the hash buffer (must be >= 16).
+     * @return An active guard, or a null guard when the category is
+     * disabled or hashSize is under 16.
      */
-    static SpanGuard
+    [[nodiscard]] static SpanGuard
     hashSpan(
         TraceCategory const cat,
         std::string_view const name,
@@ -414,8 +416,10 @@ public:
      * @param parentSpanId    Pointer to 8 bytes of parent span ID.
      * @param parentSpanSize  Size of parent span ID buffer (must be 8).
      * @param traceFlags      Trace flags from remote context.
+     * @return An active guard, or a null guard when the category is
+     * disabled, hashSize is under 16, or parentSpanSize is not 8.
      */
-    static SpanGuard
+    [[nodiscard]] static SpanGuard
     hashSpan(
         TraceCategory const cat,
         std::string_view const name,

include/xrpl/telemetry/TraceContextPropagator.h

@@ -42,7 +42,7 @@ namespace xrpl::telemetry {
  * @return An OTel Context with the extracted parent span, or an empty
  * context if the protobuf fields are missing or invalid.
  */
-inline opentelemetry::context::Context
+[[nodiscard]] inline opentelemetry::context::Context
 extractFromProtobuf(protocol::TraceContext const& proto)
 {
     namespace trace = opentelemetry::trace;

include/xrpl/telemetry/TraceContextValidation.h

@@ -57,7 +57,7 @@ namespace xrpl::telemetry {
  * @param traceId The raw trace_id bytes from a protobuf TraceContext.
  * @return true if usable as a trace identifier, false otherwise.
  */
-inline bool
+[[nodiscard]] inline bool
 isValidTraceId(std::string const& traceId)
 {
     return traceId.size() == 16 && std::ranges::any_of(traceId, [](char c) { return c != 0; });
@@ -69,7 +69,7 @@ isValidTraceId(std::string const& traceId)
  * @param spanId The raw span_id bytes from a protobuf TraceContext.
  * @return true if usable as a span identifier, false otherwise.
  */
-inline bool
+[[nodiscard]] inline bool
 isValidSpanId(std::string const& spanId)
 {
     return spanId.size() == 8 && std::ranges::any_of(spanId, [](char c) { return c != 0; });
@@ -86,7 +86,7 @@ isValidSpanId(std::string const& spanId)
  * @param tc The protobuf TraceContext received from a peer.
  * @return true if both ids are present and valid, false otherwise.
  */
-inline bool
+[[nodiscard]] inline bool
 isValidTraceContext(protocol::TraceContext const& tc)
 {
     return tc.has_trace_id() && isValidTraceId(tc.trace_id()) && tc.has_span_id() &&

src/xrpld/telemetry/TxTracing.h

@@ -32,8 +32,12 @@ namespace xrpl::telemetry {
  *  trace_id is derived from txID[0:16]. If the incoming message carries
  *  a protobuf TraceContext with a valid span_id, it is used as the
  *  parent to preserve relay ordering.
+ * @param txID  Transaction id; its first 16 bytes become the trace_id.
+ * @param msg   The received message, read only for its trace context.
+ * @return An active guard, or a null guard when the Transactions category
+ * is disabled. Bind it: a discarded guard ends the span immediately.
  */
-inline SpanGuard
+[[nodiscard]] inline SpanGuard
 txReceiveSpan(uint256 const& txID, [[maybe_unused]] protocol::TMTransaction const& msg)
 {
 #ifdef XRPL_ENABLE_TELEMETRY
@@ -63,8 +67,11 @@ txReceiveSpan(uint256 const& txID, [[maybe_unused]] protocol::TMTransaction cons
 /**
  * Create a "tx.process" span for transaction processing in NetworkOPs.
  *  trace_id is derived from txID[0:16].
+ * @param txID  Transaction id; its first 16 bytes become the trace_id.
+ * @return An active guard, or a null guard when the Transactions category
+ * is disabled. Bind it: a discarded guard ends the span immediately.
  */
-inline SpanGuard
+[[nodiscard]] inline SpanGuard
 txProcessSpan(uint256 const& txID)
 {
     return SpanGuard::hashSpan(