From 5fed2e2f32cfb15fff042a39f3ac82abe8948ca0 Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Fri, 9 Jan 2026 21:12:51 +0000 Subject: docs: integrate rejected events index into architecture documentation - Add rejected events index to architecture.md with two-tier system explanation - Document NGIT_REJECTED_HOT_CACHE_DURATION_SECS and NGIT_REJECTED_COLD_INDEX_EXPIRY_SECS in configuration.md - Add comprehensive rejected events metrics section to monitoring.md with Grafana queries and alerts - Explain negentropy integration with rejected index in grasp-02-proactive-sync.md - Document state event authorization defense-in-depth and rejection tracking in inline-authorization.md This integrates information from work/rejected-events-index-summary.md into the main documentation, ensuring architecture docs accurately reflect the implemented rejected events index system. --- docs/explanation/grasp-02-proactive-sync.md | 35 +++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) (limited to 'docs/explanation/grasp-02-proactive-sync.md') diff --git a/docs/explanation/grasp-02-proactive-sync.md b/docs/explanation/grasp-02-proactive-sync.md index e983316..ed8fdbf 100644 --- a/docs/explanation/grasp-02-proactive-sync.md +++ b/docs/explanation/grasp-02-proactive-sync.md @@ -729,6 +729,41 @@ If negentropy fails (relay doesn't support NIP-77, network error, etc.): 2. The sync falls back to traditional REQ+EOSE 3. No error is raised - fallback is automatic +### Integration with Rejected Events Index + +The rejected events index prevents wasteful re-fetching during negentropy sync by excluding rejected event IDs from the reconciliation process: + +**During Negentropy Reconciliation:** + +1. **Build "already have" set**: Combine event IDs from: + - Events in database + - Events in purgatory + - **Events in rejected index (hot cache + cold index)** + +2. **Send to negentropy**: This combined set represents "events we already have or don't want" + +3. **Receive differences**: Relay only sends events we don't have and haven't rejected + +4. **Process received events**: New events go through normal validation: + - If accepted → saved to database + - If rejected → added to rejected index + - If waiting for dependencies → added to purgatory + +**Why This Matters:** + +Without the rejected events index, negentropy would repeatedly download events that don't list this service or are from unauthorized maintainers, wasting bandwidth on every sync cycle. + +**Re-Processing on Dependency Arrival:** + +When a dependency is satisfied (e.g., owner announcement accepted): +1. Related entries are **invalidated** (removed) from cold index +2. If event still in hot cache → immediate re-processing +3. If event expired from hot cache → will be re-fetched on next sync (now that dependency exists) + +This prevents permanently excluding events that could become valid after dependencies arrive. + +See [work/rejected-events-index-summary.md](../../work/rejected-events-index-summary.md) for complete implementation details. + --- ## REQ+EOSE Pagination -- cgit v1.2.3