From 89b5210e5ba9483698d778c9a718451e9e7e8e3c Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Mon, 6 Jul 2026 20:54:09 +0100 Subject: [PATCH] docs(telemetry): clarify redactAccount is obfuscation, not secrecy Soften the "non-reversible" wording in Redaction.h. XRP account addresses are a public, enumerable set, so an unsalted hash is obfuscation (keeps plaintext out of traces/dashboards), not a secrecy guarantee. Document why a salt is intentionally omitted: it would break cross-node/restart correlation, the reason for hashing rather than dropping the attribute. Co-Authored-By: Claude Opus 4.8 --- include/xrpl/telemetry/Redaction.h | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/include/xrpl/telemetry/Redaction.h b/include/xrpl/telemetry/Redaction.h index 50ab17efe2..ed84ae2964 100644 --- a/include/xrpl/telemetry/Redaction.h +++ b/include/xrpl/telemetry/Redaction.h @@ -3,10 +3,10 @@ /** Account-address redaction for telemetry span attributes. Path-finding RPC handlers would otherwise emit the caller's raw - account addresses as span attributes. To keep addresses out of the - telemetry backend, they are hashed at the point of emission. This - header exposes a single pure helper that turns an address into a - short, stable, non-reversible token. + account addresses as span attributes. To keep plaintext addresses out + of the telemetry backend, they are hashed at the point of emission. + This header exposes a single pure helper that turns an address into a + short, stable, obfuscated token. Data flow: @@ -15,7 +15,15 @@ The returned token is the first 16 hex characters (lowercase) of the SHA-512Half digest of the address. It is deterministic (same address always maps to the same token) so operators can still correlate spans - for a given account, but the original address cannot be recovered. + for a given account across nodes and restarts. + + The hash is unsalted, so it is obfuscation, not a secrecy guarantee: + XRP account addresses are a public, enumerable set, so a determined + observer with the telemetry stream could rebuild the address->token + mapping. The goal here is to keep plaintext addresses out of traces + and dashboards, not to defend against a precomputation attack. A salt + is intentionally omitted because it would break cross-node/restart + correlation, which is the reason for hashing rather than dropping. A second, independent hashing layer runs in the OpenTelemetry Collector (an `attributes/hash` processor) as defense-in-depth for @@ -44,7 +52,7 @@ namespace xrpl::telemetry { -/** Hash an account address into a short, stable, non-reversible token. +/** Hash an account address into a short, stable, obfuscated token. @param addr The account address to redact (e.g. an r-address). @return The first 16 lowercase hex characters of sha512Half(addr),