# Ethereum node observatory

> Live observatory of the publicly discoverable Ethereum consensus-layer
> (beacon-chain) peer-to-peer network. Crawls discv5, queries peers over
> libp2p, geolocates IPs, aggregates the result. All data is derived from
> public protocol broadcasts.

Web app:   https://etherrays.com
REST API:  https://backend.etherrays.com
GraphQL:   https://backend.etherrays.com/graphql
HTML doc:  https://etherrays.com/llm
Terms:     https://etherrays.com/legal

## How the data is collected
- discv5 DHT crawl harvests ENRs.
- ENRs with the Ethereum mainnet fork digest are persisted.
- libp2p (TCP + Noise + Yamux + SSZ/Snappy) is used to fetch identify +
  status RPCs from active peers, yielding client name, version, OS,
  fork digest, head slot, and sync state.
- Public IPs are geolocated and ASN-resolved via a third-party service.
- Network-wide snapshots are written to a history table ~hourly.
- Recent peer-to-peer connection samples are recorded as edges for the
  animated arcs on the 3D globe.

## Update cadence (best-effort)
- discv5 crawl: continuous
- per-peer ping & status: every few minutes
- metadata refresh: hours-scale
- history snapshots: ~hourly
- API caches: 15s..5min depending on endpoint

## Pages
- /              Overview
- /countries     Country & city breakdown
- /map           Clustered world map
- /globe         3D globe with animated peer-connection arcs
- /clients       Consensus & execution client distribution & versions
- /network       Fork digests & protocol versions
- /os            Operating-system distribution
- /infrastructure  Cloud / hosting / connection-type breakdown
- /nodes         Paginated, filterable node directory
- /analyze       Time-series breakdowns with brush slider
- /history       30-day total / synced / unsynced
- /legal         Terms, privacy notes, attributions
- /llm           This page (HTML)

## REST API (cache TTL in parentheses)

Health
  GET /health

Overview & stats
  GET /api/stats
  GET /api/aggregates/overview                              (30s)
  GET /api/aggregates/filters                               (5min)

Clients, OS, geography
  GET /api/aggregates/clients?layer=cl|el                   (5min)
  GET /api/aggregates/clients/versions?layer=cl|el          (5min)
  GET /api/aggregates/os?layer=cl|el                        (5min)
  GET /api/aggregates/countries                             (5min)
  GET /api/aggregates/cities?country=XX                     (5min)

Globe & map
  GET /api/aggregates/globe-clusters?maxPerCountry=50       (1min)   maxPerCountry: 1..100
  GET /api/aggregates/peer-edges?limit=200&minHits=1        (30s)    limit: 1..1000
  GET /api/aggregates/heatmap?limit=5000                    (1min)   limit: 1..20000

Node directory
  GET /api/nodes?page=1&limit=25&sort=last_updated_at&order=desc  (15s)
  GET /api/nodes/:nodeId

Analytics
  GET /api/analytics/infrastructure                         (2min)
  GET /api/analytics/forks                                  (2min)
  GET /api/analytics/protocol-versions                      (2min)
  GET /api/analytics/client-versions?layer=cl|el            (2min)

History
  GET /api/history/metrics?from=ISO&to=ISO                  (1min)
  GET /api/history/metrics/latest
  GET /api/history/breakdown?dimension=<dim>
  GET /api/history/breakdown/current?dimension=<dim>        (2min)
  GET /api/history/breakdown/series?dimension=<dim>&from=ISO&to=ISO  (1min)
  Valid dimensions: status, cl_client, el_client, cl_os, el_os,
    country, cl_network, el_network, cloud_provider, hosting_type,
    fork_digest, protocol_version.

GraphQL
  POST /graphql      (introspection enabled)

## Key data fields per node
node_id, enr, ip, tcp_port, udp_port, status,
cl_client_name, cl_client_version, cl_agent,
el_client_name, el_client_version,
cl_fork_digest, cl_head_slot, cl_finalized_root, cl_synced,
geo_country, geo_region, geo_city, geo_latitude, geo_longitude,
geo_asn, geo_isp, cloud_provider, hosting_type,
discovered_at, last_active_at, last_updated_at.

## Limitations
- Lower bound on the real network: many nodes never publish a routable ENR.
- Client labels are self-reported and can be spoofed.
- IP-to-location is approximate; cloud / VPN IPs distort country counts.
- cl_synced reflects the most recent status RPC, not real-time truth.
- Globe arcs are sampled, not an exhaustive adjacency graph.
- No availability guarantee; service may change or disappear without notice.

## Acceptable use for automated clients
- Prefer cached endpoints, respect Cache-Control, back off on 429/5xx.
- Sustained: <= ~1 rps. Bursts: ~5 rps tolerated; rate-limits apply.
- Identify your bot in User-Agent with a contact URL or e-mail.
- No commercial bulk redistribution.
- Pull what you need, persist on your side, run analyses there.

## Suggested citation
Ethereum node observatory, https://etherrays.com, accessed YYYY-MM-DD.
Data derived from public discv5 / libp2p broadcasts; figures are
best-effort and represent a lower bound on the discoverable mainnet
network.

## Terms
Provided strictly "as is", "as available", with all faults and no
warranties of any kind. No guarantee of continuity, accuracy, or
availability. Full terms: https://etherrays.com/legal