From 9bfa3cc32cf73934d74c4526ef243a4f74e22836 Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Wed, 23 Sep 2026 18:00:34 +0100 Subject: [PATCH] docs(telemetry): Account addresses are public and not hashed Rewrite the privacy policy (design decisions section 2.4.4) and the two plan summaries that still described account hashing and a configurable redaction. Add the two account attributes to the path-finding attribute table and describe pathfind_dest_currency as the rendered asset. --- OpenTelemetryPlan/02-design-decisions.md | 78 ++++++++++--------- .../05-configuration-reference.md | 2 +- OpenTelemetryPlan/OpenTelemetryPlan.md | 2 +- 3 files changed, 42 insertions(+), 40 deletions(-) diff --git a/OpenTelemetryPlan/02-design-decisions.md b/OpenTelemetryPlan/02-design-decisions.md index cb435951f4..e39e0bc4db 100644 --- a/OpenTelemetryPlan/02-design-decisions.md +++ b/OpenTelemetryPlan/02-design-decisions.md @@ -240,7 +240,7 @@ keys (the dotted form is reserved for resource scope per §2.3.3). | -------------------- | ------ | ------------------------------------- | | `tx_hash` | string | Transaction hash (hex) | | `tx_type` | string | `"Payment"`, `"OfferCreate"`, etc. | -| `tx_account` | string | Source account (redacted in prod) | +| `tx_account` | string | Source account, raw r-address | | `tx_sequence` | int64 | Account sequence number | | `tx_fee` | int64 | Fee in drops | | `tx_result` | string | `"tesSUCCESS"`, `"tecPATH_DRY"`, etc. | @@ -299,12 +299,14 @@ keys (the dotted form is reserved for resource scope per §2.3.3). #### 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 | +| Key | Type | Description | +| -------------------------- | ------ | ---------------------------------------------------------------------- | +| `pathfind_source_account` | string | Source r-address, raw | +| `pathfind_dest_account` | string | Destination r-address, raw | +| `pathfind_source_currency` | string | Source currency code | +| `pathfind_dest_currency` | string | Destination asset: `XRP`, `/`, or an MPT issuance id | +| `pathfind_path_count` | int64 | Number of paths found | +| `pathfind_cache_hit` | bool | RippleLineCache hit | #### TxQ Attributes @@ -383,50 +385,50 @@ The following data is explicitly **excluded** from telemetry collection: #### 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 | -| **Configurable Redaction** | Sensitive fields can be excluded via `[telemetry]` config section | -| **Collector Tail Sampling** | xrpld head sampling is fixed at 1.0 (every span emitted); the collector retains ~10% of non-error traces, reducing stored data exposure | -| **Sampling** | Only 10% of traces recorded by default, reducing data exposure | -| **Local Control** | Node operators have full control over what gets exported | -| **No Raw Payloads** | Transaction content is never recorded, only metadata (hash, type, result) | -| **Collector-Level Filtering** | Additional redaction/hashing can be configured at OTel Collector | +| Mechanism | Description | +| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Account Addresses** | Emitted raw (`pathfind_source_account`, `pathfind_dest_account`). An account address is a public ledger identifier; hashing it protects nothing and breaks the join against explorers, RPC and logs | +| **Collector Tail Sampling** | xrpld head sampling is fixed at 1.0 (every span emitted); the collector retains ~10% of non-error traces, reducing stored data exposure | +| **Sampling** | Only 10% of traces recorded by default, reducing data exposure | +| **Local Control** | Node operators have full control over what gets exported | +| **No Raw Payloads** | Transaction content is never recorded, only metadata (hash, type, result) | +| **Collector-Level Filtering** | Available for a future genuinely sensitive attribute via an `attributes` processor. None is shipped, and none must be added for account addresses | -#### Account Address Hashing +#### Account Addresses -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: +Account addresses are emitted **raw**, at every layer: -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. The - helper emits the first 16 characters of `sha512Half(address)` as - lowercase hex — deterministic (spans for one account still correlate) - but non-reversible. -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. +1. **SDK-side** (this node): the path-finding RPC handlers set + `pathfind_source_account` / `pathfind_dest_account` to the request's + r-address, only when it parses as one, and `pathfind_dest_currency` to `to_string(Asset)`, + which carries the IOU issuer's r-address. The rationale sits on the attribute + constants in `PathFindSpanNames.h`. +2. **Collector-side**: no collector configuration in this repository hashes + or deletes these attributes. + +Why raw: an r-address is a public, enumerable identifier on the ledger. An +unsalted hash of it is reversible by table lookup, so it protects nothing, and +it breaks the one thing the attribute is for: joining a span to the account as +explorers, RPC responses and logs show it. The helper `redactAccount()` +(`xrpl::telemetry`, `Redaction.h`) remains available for a value that is +genuinely private, but it is applied to no span. #### Collector-Level Data Protection -The OpenTelemetry Collector can be configured (via an `attributes` processor) -to hash or redact sensitive attributes before export — for example, hashing -`pathfind_source_account` / `pathfind_dest_account`, deleting `peer_address` -to drop IP addresses, and deleting `params` to redact request parameters. +No hashing or redaction processor is shipped. If a future span introduces a +genuinely sensitive attribute, an `attributes` processor in the collector is the +place to strip it, and the attribute is added to the §2.4 catalogue with that +note in the same change. Account addresses are not such an attribute. #### 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. +often disabled due to high volume) select which spans are emitted. There is no +redaction setting: account addresses are public and are emitted raw. -> **Key Principle**: Telemetry collects **operational metadata** (timing, counts, hashes) — never **sensitive content** (keys, balances, amounts, raw payloads). +> **Key Principle**: Telemetry collects **operational metadata** (timing, counts, hashes, public identifiers) — never **sensitive content** (keys, balances, amounts, raw payloads). --- diff --git a/OpenTelemetryPlan/05-configuration-reference.md b/OpenTelemetryPlan/05-configuration-reference.md index c97d47d6e4..aad0ec27d0 100644 --- a/OpenTelemetryPlan/05-configuration-reference.md +++ b/OpenTelemetryPlan/05-configuration-reference.md @@ -105,7 +105,7 @@ The development collector enables an OTLP receiver on both gRPC (`0.0.0.0:4317`) ### 5.5.2 Production Configuration -The production collector adds TLS on the OTLP gRPC receiver and a richer processor chain: a `memory_limiter` (OOM guard), `batch` (5s timeout, size 512), `tail_sampling`, and an `attributes` processor that hashes sensitive fields (e.g. `tx_account`) and stamps `deployment.environment`. Tail sampling keeps all `ERROR` traces, slow consensus rounds (>5s) and slow RPC requests (>1s), and probabilistically samples the remainder at 10%. Exporters target Grafana Tempo (TLS) and Elastic APM; `health_check` and `zpages` extensions are enabled for operability. +The production collector adds TLS on the OTLP gRPC receiver and a richer processor chain: a `memory_limiter` (OOM guard), `batch` (5s timeout, size 512), `tail_sampling`, and an `attributes` processor that stamps `deployment.environment`. Account addresses are public identifiers and are not hashed at any layer. Tail sampling keeps all `ERROR` traces, slow consensus rounds (>5s) and slow RPC requests (>1s), and probabilistically samples the remainder at 10%. Exporters target Grafana Tempo (TLS) and Elastic APM; `health_check` and `zpages` extensions are enabled for operability. --- diff --git a/OpenTelemetryPlan/OpenTelemetryPlan.md b/OpenTelemetryPlan/OpenTelemetryPlan.md index 51e83b6d65..687225f03a 100644 --- a/OpenTelemetryPlan/OpenTelemetryPlan.md +++ b/OpenTelemetryPlan/OpenTelemetryPlan.md @@ -130,7 +130,7 @@ The OpenTelemetry C++ SDK is selected for its CNCF backing, active development, Span naming follows a hierarchical `.` convention (e.g., `rpc.submit`, `tx.relay`, `consensus.round`). Context propagation uses W3C Trace Context headers for HTTP and embedded Protocol Buffer fields for P2P messages. The implementation coexists with existing PerfLog and Insight observability systems through correlation IDs. -**Data Collection & Privacy**: Telemetry collects only operational metadata (timing, counts, hashes) — never sensitive content (private keys, balances, amounts, raw payloads). Privacy protection includes account hashing, configurable redaction, sampling, and collector-level filtering. Node operators retain full control over telemetry configuration. +**Data Collection & Privacy**: Telemetry collects only operational metadata (timing, counts, hashes) — never sensitive content (private keys, balances, amounts, raw payloads). Account addresses are public ledger identifiers and are emitted raw; there is no redaction setting. Trace volume is reduced, where wanted, by collector-side sampling. Node operators retain full control over telemetry configuration. ➡️ **[Read full Design Decisions](./02-design-decisions.md)**