Redesign bloom filter parameters with mathematical justification

Analysis revealed original parameters (4KB, k=7) were oversized:
- Expected filter occupancy ~250-800 entries, not ~4,096
- Original FPR estimates in docs were incorrect (5-7x optimistic)
- d^(2K) formula overcounted by assuming mesh vs tree structure

New v1 parameters:
- Filter size: 1 KB (was 4 KB) - 75% bandwidth reduction
- Hash functions: k=5 (was 7) - optimal for 800-1600 entries
- K-hop scope: 2 (unchanged)

Added forward compatibility via size_class field:
- Power-of-2 sizes (512B, 1KB, 2KB, 4KB) enable folding
- v1 requires size_class=1; future versions can negotiate larger
- Receivers can fold larger filters down to preferred size

Updated docs:
- fips-routing.md: Part 1 rewritten with math foundation
- fips-gossip-protocol.md: §3 and Appendix A.2 wire format
- fips-architecture.md: Configuration parameters
This commit is contained in:
Johnathan Corgan
2026-02-02 14:41:28 +00:00
parent 021bf69d73
commit 7d5d1adedc
3 changed files with 168 additions and 36 deletions
+5 -2
View File
@@ -906,13 +906,16 @@ the limit but need not enforce it strictly.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `filter.size` | u32 | 32768 | Filter size in bits (4KB) |
| `filter.hash_count` | u8 | 7 | Number of hash functions |
| `filter.size_class` | u8 | 1 | Size class: 0=512B, 1=1KB, 2=2KB, 3=4KB |
| `filter.hash_count` | u8 | 5 | Number of hash functions |
| `filter.scope` | u8 | 2 | TTL for filter propagation (K) |
| `filter.refresh.interval` | duration | 60s | Periodic FilterAnnounce refresh |
| `filter.update.debounce` | duration | 500ms | Min interval between updates |
| `filter.stale.threshold` | duration | 300s | Consider peer's filter stale |
v1 protocol requires `size_class=1` (1 KB filters). The size_class field is
present in the wire format for forward compatibility with larger filters.
### Discovery Protocol
| Parameter | Type | Default | Description |