Module bucket_refresh 

Routing-table bucket refresh (ADR 022 §Routing Table — “Bucket refresh interval | 1 hour”).

Every routing-table bucket holds peers at a specific XOR-distance prefix from self.node_id. As nodes leave the network those peers’ entries silently die — without refresh, a long-lived node’s buckets fill with stale entries and lookup convergence degrades.

The fix per ADR 022 §Routing Table is to periodically issue a FindNode(random_id_in_bucket) to one peer in each bucket, every hour. Live peers in that distance shell respond with their own K-closest, populating the bucket with fresh entries.

Implementation: a single tokio task wakes on a 1-hour ticker and refreshes every non-empty bucket per tick (see BUCKET_REFRESH_TICK for the rate-budget argument). For each non-empty bucket it synthesises a random NodeId whose XOR distance to self falls in that bucket’s range and runs FindNode against the bucket’s most-recently-seen peer; the per-bucket RPCs fan out in parallel.

This is a “best-effort hygiene” task: a refresh that fails (peer unreachable, timeout) is silently ignored — the next tick will try the next bucket. Failure has no operator-actionable signal.

Constants

BUCKET_REFRESH_TICK

Bucket-refresh tick interval. ADR 022 §Routing Table specifies “1 hour” as the refresh interval per bucket — we run every non-empty bucket per tick so each populated bucket gets the ADR-mandated hourly refresh. At realistic scale (≤30 populated buckets even in a 500-node network) this is ≤30 FindNode RPCs per hour, comfortably within the routing-table peers’ own per-IP rate limit (100 req/s by default).

Functions

run_bucket_refresh

Long-running task: every BUCKET_REFRESH_TICK runs a FindNode(random_id_in_bucket) against each non-empty bucket’s most-recently-seen peer in parallel. Exits on stop_rx.