docs(discovery): drop the speculative sections and home the metric with the rest

"If lean ever meets a real network" and the two `tcp` notes described a future
whose shape is not settled: what to do about a live fork schedule, and the
interop cost of publishing no `tcp` entry. Neither is something an operator
reading this page acts on today, and both would need rewriting rather than
updating once lean's fork story lands.

`lean_discovered_peers_dialed_total` moves to `docs/metrics.md`, where every
other metric is already documented in table form. It goes under the custom
(non-leanMetrics) heading, since that table's Supported column tracks spec
conformance and discv5 discovery is ours alone.

Author: MegaRedHand

CLAUDE.md

@@ -283,7 +283,7 @@ actual_slot = finalized_slot + 1 + relative_index
 ### Peer Discovery (discv5, opt-in)
 - Off by default; `--discovery.enable` plus `--discovery.port` (own UDP socket, must differ from `--gossipsub-port`)
 - Reuses ethrex's `DiscoveryServer` + `PeerTable` with discv4 disabled; `spawn` takes the prepared lean ENR, so the record ethrex serves is the one we report
-- ENR follows the beacon phase0 spec: `ip`/`udp`/`quic`/`secp256k1`/`eth2`/`attnets`, deliberately **no** `tcp`
+- ENR follows the beacon phase0 spec: `ip`/`udp`/`quic`/`secp256k1`/`eth2`/`attnets`
 - Admission mirrors lighthouse: `eth2.fork_digest` must match, `next_fork_*` may differ, `quic` entry required. Handed to the peer table as `LeanFilter: PeerFilter`, so records are judged on arrival, not at dial time; a reject is re-judged on a higher-`seq` ENR
 - Candidates ranked by uncovered attestation subnets. See [`docs/discovery.md`](docs/discovery.md)
 

docs/discovery.md

@@ -53,9 +53,6 @@ The layout follows the discovery domain of the beacon-chain
 | `eth2` | SSZ `ENRForkID`, 16 bytes |
 | `attnets` | subscribed attestation subnet bitfield |
 
-There is no `tcp` entry: the spec defines it as the libp2p TCP listening port
-and ethlambda speaks QUIC only.
-
 The local ENR is logged once at startup.
 
 This same record is handed to ethrex's `DiscoveryServer`, so it is what answers
@@ -102,8 +99,8 @@ answer different questions:
 Neither absence is an error, and a record carrying just one of them is still
 kept. The ENRs `lean-quickstart` generates today carry `ip`/`quic`/`secp256k1`
 and no `udp`, so they stay reachable but contribute nothing to discovery. Every
-beacon-chain bootnode published today is the mirror image: `ip`/`udp`/`tcp` and
-no `quic`, usable as a discv5 seed but never dialed. A record with neither is
+beacon-chain bootnode published today is the mirror image: a `udp` port but no
+`quic`, usable as a discv5 seed but never dialed. A record with neither is
 dropped with a warning, as is one missing an `ip` or a `secp256k1` key.
 
 The ENR a node logs at startup is only useful to a peer if that node was
@@ -114,18 +111,6 @@ names no reachable host. Set `--discovery.advertise-ip` before pointing other
 nodes at this one's ENR: `127.0.0.1` on a local devnet, or the host's public
 address otherwise.
 
-## If lean ever meets a real network
-
-Two details are worth copying the day lean peers with a network carrying a live
-fork schedule:
-
-- Learn the fork digest by plurality vote over discovered ENRs rather than
-  hardcoding it, so a fork does not strand the node. Bootnode records are poor
-  witnesses here: mainnet's still advertise the phase0 digest.
-- Gossip message ids follow Altair's function, which inserts the topic length
-  and topic bytes between the domain and the payload. Phase0's shorter form
-  produces ids no peer agrees with, which breaks IWANT/IHAVE silently.
-
 ## Known limitations
 
 ### One lean devnet is not separated from another
@@ -138,18 +123,6 @@ another**: two devnets running this code will peer with each other. Closing that
 gap requires lean adopting a genesis-derived fork digest, which is a
 cross-client change to gossip topic names.
 
-### A beacon-chain client cannot discover us, and `tcp` is why
-
-Beyond the fork digest never matching a real beacon network, there is a second,
-independent blocker. Lighthouse's discovery predicate is stricter than the spec
-text: alongside the `fork_digest` comparison it requires
-`enr.tcp4().is_some() || enr.tcp6().is_some()`, and it applies that as a
-discv5 query filter, so a `tcp`-less record is dropped before lighthouse's dial
-logic ever sees it. Our records deliberately carry no `tcp`, so they would be
-filtered out even if the digests did match. That is the right trade for a
-QUIC-only client, but it means the omission is a real interop cost and not a
-free simplification.
-
 ### `attnets` is not a fixed-width SSZ `Bitvector`
 
 The spec's `attnets` is `Bitvector[ATTESTATION_SUBNET_COUNT]`, a constant every
@@ -160,8 +133,3 @@ lengths. The bit-packing convention is identical to the spec's; only the width
 is negotiable. Readers tolerate a foreign length by treating bits past the end
 as unset, and a peer's advertised subnets are clamped to the local committee
 count before they influence anything.
-
-## Metrics
-
-`lean_discovered_peers_dialed_total` counts dials initiated by discovery.
-Connection outcomes are covered by the existing peer connect/disconnect metrics.

docs/metrics.md

@@ -126,6 +126,18 @@ The metrics below are not part of the [leanMetrics specification](https://github
 | `lean_reqresp_request_size_bytes` | Histogram | Bytes size of a req/resp request (raw SSZ or snappy on-wire) | On req/resp request send/receive | protocol=status,blocks_by_root<br>compression=raw,snappy | 64, 128, 256, 512, 1024, 4096, 16384, 65536 |
 | `lean_reqresp_response_chunk_size_bytes` | Histogram | Bytes size of a single req/resp response chunk (raw SSZ or snappy on-wire) | On req/resp response chunk send/receive | protocol=status,blocks_by_root<br>compression=raw,snappy | 128, 1024, 10000, 100000, 500000, 1000000, 5000000, 10000000 |
 
+### Peer Discovery
+
+Only emitted when discv5 discovery is enabled (`--discovery.enable`); see
+[Peer discovery](./discovery.md). Counts dials discovery initiated, as opposed to
+the static bootnode dials every node makes. Connection outcomes are not repeated
+here: a discovery dial that succeeds or fails shows up in
+`lean_peer_connection_events_total` like any other.
+
+| Name | Type | Usage | Sample collection event | Labels |
+|------|------|-------|-------------------------|--------|
+| `lean_discovered_peers_dialed_total` | Counter | Peers dialed as a result of discv5 discovery | On dialing a discovered peer | |
+
 ### Gossip Arrival Timing
 
 These histograms record the absolute distance between a gossip message's arrival and the start of the interval it was due in, so an arrival that is early by some amount and one that is late by the same amount land in the same bucket; the counters' `position` label is what tells them apart. `inside` means the message arrived within the interval it was due in, not merely somewhere in the right slot: an attestation for slot 10 that lands during slot 10's interval 2 is `after`, not `inside`, since it missed the AttestationProduction interval it was actually due in.