CLPR-4.5: Gossip-based peer discovery and reciprocity selection

Story CLPR-4.5: Gossip-Based Peer Discovery and Reciprocity Selection

Parent Epic: CLPR-4: Hiero Endpoint

Objective

Implement the off-chain gossip-based peer endpoint discovery protocol and reciprocity-based peer selection.

Acceptance Criteria

• AC-1: On startup, the endpoint module reads seed endpoints from the peer's ClprLedgerConfiguration (obtained during connection registration and updated via ConfigUpdate).
• AC-2: Endpoint contacts seed endpoints via discoverEndpoints RPC to learn about additional peer endpoints.
• AC-3: Through iterative discovery, endpoints converge on a view of the peer network.
• AC-4: Discovered peer data is ephemeral (in-memory, not persisted to the Merkle tree). Resets on restart (re-bootstraps from seed endpoints).
• AC-5: Discovery responses are throttled (configurable rate limit per caller, e.g., 1 request/minute/IP).
• AC-6: Reciprocity scoring: peers that provide bundles with messages during sync get a reputation bonus. Peers that only request messages without providing any get deprioritized.
• AC-7: Freeloading cannot be faked — providing a valid bundle with messages requires having actual messages to send.
• AC-8: When the active consensus roster changes, the endpoint count is updated for per-endpoint throttle calculation.

Notes

• Replaces the old model where peer endpoint data was stored in PEER_ENDPOINT_ROSTERS state and propagated via EndpointJoin/EndpointLeave control messages.
• The new model avoids O(N × M) gas cost of propagating endpoint changes across N endpoints and M connections.
• No authentication is required for discovery — if a peer provides false endpoint info, the worst outcome is wasted connection attempts.

Dependencies

• CLPR-4.1 (gRPC server — hosts discoverEndpoints RPC)
• CLPR-4.3 (sync orchestration — uses discovered peers)
• CLPR-1.4 (Connection with verified peer config containing seed endpoints)

Risk

Medium — Gossip convergence. Discovery throttling. Reciprocity scoring calibration.

Start with the discoverEndpoints RPC dependency, then trace ClprLedgerConfiguration from connection registration and ConfigUpdate into the sync orchestration described in the dependencies. Review how the active consensus roster supplies the endpoint count for throttling. Done means satisfying AC-1 through AC-8, including ephemeral iterative discovery, rate limiting, reciprocity scoring, and roster-aware throttle updates.