Monitoring and Diagnostics

Date: 2026-03-14 Status: Draft

Problem Statement

The protocol specifies pact formation, challenge-response, gossip routing, and tiered retrieval — but provides no diagnostic tools. When a data request fails, a pact degrades, or gossip doesn't reach a user's content, there is no way to understand why. Users see the symptom (content not loading, partner dropped) but never the cause (relay dropping kind 10054, partner's disk full, gossip TTL exhausted before reaching any holder).

This is especially damaging during the Bootstrap and Hybrid phases (0–15 pacts), when failures are most likely and the user's trust in the protocol is most fragile. A user who loses a pact with no explanation will assume the protocol is broken, not that their partner went offline for 73 hours.

This document specifies the diagnostic surface that clients must expose.

Design Principles

1. Local-first. All diagnostic data is computed and stored on the user's device. Diagnostic logs are never published to relays, never shared with pact partners, and never leave the device unless the user explicitly exports them.
2. Privacy by default. Diagnostic displays use pubkey nicknames (from kind 0 metadata), not raw pubkeys. Export formats strip identifying information unless the user opts in.
3. Progressive disclosure. Standard users see high-level health indicators. Developer mode exposes full protocol traces. The default view never mentions event kinds, hash computations, or relay WebSocket frames.
4. No new event kinds. Diagnostics are purely client-side. No new protocol messages, no relay requirements, no changes to the pact state machine.

1. Pact Health Dashboard

Per-Pact Health Indicators

Each active, standby, and degraded pact is represented as a card in the client's pact management view. The card displays:

Color coding:

• Green: challenge rate >= 90%, volume within 30% tolerance, partner seen in last 24h
• Yellow: challenge rate 70–89%, volume drifting toward tolerance, partner offline 24–48h
• Red: challenge rate < 70%, volume over tolerance, partner offline > 48h

Aggregate Network Health

A summary view at the top of the pact management screen:

2. Gossip Propagation Debugging

Retrieval Trace

When the client retrieves content (events for a followed user), it records which delivery tier succeeded and displays a trace in the event detail view (accessible via long-press or info button):

Trace format:

Retrieved from pact partner Alice (Tier 1, cached endpoint, 45ms)

Found via gossip through Bob → Carol (Tier 2, 2 hops, 180ms)

Fell back to relay wss://relay.example.com (Tier 4, 220ms)

Failed: content not found (all tiers exhausted, 4.2s total)

The trace records:

• Tier used (0 = BLE mesh, 1 = cached endpoints, 2 = gossip, 3 = storage peers via DVM, 4 = relay fallback)
• For gossip: the forwarding path (which peers relayed the request)
• Latency per tier attempt
• Why lower-numbered tiers failed (timeout, no holders found, relay error)

Display in standard mode: Single line summarizing the source ("From your storage network" or "From relay").

Display in developer mode: Full multi-line trace with tier numbers, hop paths, and timing.

Gossip Reach Estimate

The client estimates how many nodes can serve the user's content by counting:

• Active pact partners holding the user's events
• Standby pact partners holding the user's events
• Cached copies (estimated from recent kind 10058 data offer responses to requests for the user's data)

Displayed as: "Your content is held by ~23 peers across the network."

This is a lower-bound estimate. Cascading read-caches make the true reach higher for popular content, but the client cannot observe caches it doesn't know about.

3. Relay Interaction Logging

Relay Usage Breakdown

The client maintains a local log of which relays are used for which purpose:

Relay Health Metrics

Per relay, tracked over a rolling 7-day window:

Relay Rejection Log

When a relay rejects an event or request, the client logs the reason:

Privacy Constraint

All relay logs are stored in the client's local database. They are never published to any relay, never included in any event, and never transmitted to any peer. The log is viewable only in the client's settings screen. Export is available as a local file for debugging, with relay URLs included but no event content.

4. Challenge-Response Diagnostics

Per-Partner Challenge History

For each pact partner, the client maintains a rolling log of the last 30 challenges (sent and received):

Failure Diagnosis

When a challenge fails, the client categorizes the failure:

Reliability Score Trend

The client displays a reliability score trend line for each partner:

• Current score (exponential moving average, alpha = 0.95)
• 30-day trend: improving, stable, or degrading
• Visual: sparkline or simple arrow indicator

Alerts:

• "Partner [name] reliability dropped to 75% — pact is now degraded. Seeking replacement." (transition to Degraded state)
• "Partner [name] has failed 3 consecutive challenges. If this continues, the pact will be dropped." (approaching Failed threshold)
• "Partner [name] recovered to 85% — pact restored to Active." (transition back from Degraded)

Degradation Threshold Warning

The client alerts the user before a pact transitions to a terminal state:

5. WoT Visualization

Social Graph View

The client renders a network graph of the user's social relationships:

• Center: The user's identity
• Ring 1 (Inner Circle): Mutual follows — pact partners and close contacts
• Ring 2 (Orbit): Authors the user interacts with heavily, plus referrals from Inner Circle
• Ring 3 (Horizon): 2-hop contacts reachable through the WoT

Node size scales with interaction score. Edge thickness represents relationship strength (mutual follow, one-way follow, pact partner).

Pact Overlay

Toggling the pact overlay highlights which WoT contacts have active pacts with the user:

Trust Score Distribution

A histogram showing the distribution of WoT distances for the user's pact partners:

• How many partners are mutual follows (distance 1)
• How many are 2-hop contacts (distance 2)
• Whether the pact network is concentrated in one social cluster or distributed

Community Detection

Visual clustering of the user's WoT graph using a force-directed layout:

• Clusters of densely connected contacts are grouped together
• Pact partners that span clusters provide structural resilience (if one cluster goes offline, partners in other clusters remain)
• The client highlights if all pact partners are in a single cluster: "Your pact partners are concentrated in one social group. Consider forming pacts with contacts in other communities for better resilience."

6. Health Check Command

User-Initiated Health Check

The client provides a "Check Network Health" action (accessible from the pact management screen or settings). This runs a series of tests and returns a structured report.

Test Suite

Report Format

Network Health: Good (5/6 checks passed)

[PASS] Pact partners: 17/18 reachable (Carol offline 2h — within normal range)
[PASS] Relay connectivity: 4/4 relays connected
[PASS] Device keys: Valid, published to 3 relays
[PASS] Checkpoint: 6 hours old
[WARN] Relay compatibility: wss://relay-x.com does not accept kind 10054
[PASS] Volume balance: All pacts within tolerance

Suggested actions:
  - Consider replacing wss://relay-x.com for pact communication (does not support challenge events)

Lightweight Auto-Check

On app launch, the client runs a lightweight version (relays + device key validity only — no partner pings). If issues are detected, the client shows a non-intrusive notification: "1 relay is unreachable. Tap to see details."

Full health check is never run automatically — it generates observable NIP-46 traffic to all partners, which could be a timing signal. Only the user initiates it.

7. Protocol-Level Tracing (Developer Mode)

Activation

Developer mode is enabled via a hidden settings toggle (e.g., tap version number 7 times). It is never on by default. When enabled, the client logs full protocol-level traces to a local buffer (circular buffer, configurable size, default 10 MB).

Event Lifecycle Trace

Trace the full lifecycle of a single event from publish to delivery:

[14:03:01.234] EVENT PUBLISH kind=1 id=abc123
[14:03:01.240] → Signed with device key dev_xyz
[14:03:01.241] → root_identity tag: root_abc
[14:03:01.245] → Published to wss://relay-a.com (OK, 4ms)
[14:03:01.248] → Published to wss://relay-b.com (OK, 7ms)
[14:03:01.301] → Published to wss://relay-c.com (OK, 60ms)
[14:03:01.302] → Forwarded to 18 pact partners via storage sync
[14:03:02.100] → Pact partner Bob confirmed receipt (798ms)
[14:03:02.340] → Pact partner Carol confirmed receipt (1038ms)
[14:03:05.000] → 16/18 partners confirmed within 4s

Pact Negotiation Trace

Step-by-step pact formation:

[10:00:00.000] PACT REQUEST published kind=10055 volume=42MB
[10:00:12.400] OFFER received kind=10056 from npub1abc... (volume=38MB, WoT distance=1)
[10:00:12.401]   Volume match: 38/42 = 0.90 (within ±30%)
[10:00:12.402]   WoT check: mutual follow, distance=1 (PASS)
[10:00:12.403]   Account age: 14 months (PASS, min=7 days)
[10:00:12.404]   Capacity check: 19/43 active+standby (PASS)
[10:00:12.500] OFFER accepted → publishing kind 10053
[10:00:12.600] PACT ACTIVE with npub1abc... — initial reliability=0.90
[10:00:12.601] First challenge scheduled in 14h 22m (jittered)

Challenge-Response Trace

Full round-trip with timing:

[08:00:00.000] CHALLENGE SENT kind=10054 to npub1abc...
[08:00:00.001]   nonce=a1b2c3... range=[47..53] (7 events)
[08:00:00.002]   via wss://relay-a.com (primary)
[08:00:00.003]   expected hash=d4e5f6...
[08:00:04.200] RESPONSE RECEIVED from npub1abc...
[08:00:04.201]   response hash=d4e5f6... (MATCH)
[08:00:04.202]   latency=4198ms
[08:00:04.203]   reliability score: 0.91 → 0.91 (no change, pass)

Gossip Propagation Trace

Track a data request through the gossip network:

[12:00:00.000] DATA REQUEST kind=10057 for target hash=h(pubkey||date)
[12:00:00.001]   Tier 0 (BLE): no mesh peers available
[12:00:00.002]   Tier 1 (cached endpoints): 2 endpoints known
[12:00:00.050]     endpoint wss://peer1:8080 — timeout (50ms)
[12:00:00.100]     endpoint wss://peer2:9090 — connected, no data
[12:00:00.101]   Tier 2 (gossip): broadcasting to 20 peers, TTL=3
[12:00:00.180]     Bob forwarded → Carol responded (2 hops, 80ms)
[12:00:00.181]     DATA OFFER received kind=10058 from Carol
[12:00:00.250]     Fetching events from Carol... 14 events, 23 KB
[12:00:00.251]     Signature verification: 14/14 valid
[12:00:00.252]     Merkle root check against checkpoint: PASS
[12:00:00.253]   RETRIEVAL COMPLETE: Tier 2, 253ms total

Trace Export

Developer mode traces can be exported as a JSON file for debugging. The export includes:

• All trace entries in the buffer
• Client version and platform
• Current pact state summary (partner count, states — no pubkeys unless the user opts in)
• Relay list and health metrics

Pubkeys are replaced with pseudonyms (Partner-1, Partner-2) by default. Full pubkeys are included only if the user explicitly enables "include identities in export."

8. Relay Compatibility Reporting

Compatibility Test

The client can test a relay against Gozzip's requirements. This is useful when adding a new relay to the user's NIP-65 list or when debugging pact communication failures.

Compatibility Score

Each relay receives a score based on test results:

The client displays the score when the user views relay details or adds a new relay.

Compatibility Warnings

The client warns the user when a relay in their active configuration fails compatibility:

• "wss://relay.com does not support kind 10054. Challenge-response for pacts using this relay may fail."
• "wss://relay.com rejects events larger than 16 KB. Large checkpoints may not be publishable here."
• "wss://relay.com does not support NIP-46. This relay cannot be used for pact communication."

Community Compatibility List

The client can fetch and display a community-maintained relay compatibility list:

• Published as a replaceable event (kind 30078, d tag = "gozzip-relay-compat") by a well-known project pubkey
• Contains relay URLs and their last-tested compatibility scores
• Updated periodically by automated testing infrastructure
• Client merges community data with its own local test results (local results take precedence)
• The user can disable community list fetching (opt-out for privacy)

Storage and Retention

All diagnostic data is stored in the client's local database:

Total estimated storage for a user with 20 pacts, 5 relays, and standard usage: approximately 2–5 MB. Developer mode adds up to 10 MB.

Implementation Priority

Priorities 1–4 should ship with the first client release. Priorities 5–6 should ship within 3 months. Priorities 7–8 can ship when developer demand justifies the effort.