Nodes & mesh

P2P participation and public map presence are related but separate. The P2P process exchanges peer and block data; the public mesh API contains only coarse, opt-in telemetry and never exposes operator IP addresses.

GET/api/mesh

Public peer list plus live Genesis health overlay for maps and status UIs.

bash

curl -fsS https://grid-compute.com/api/mesh | jq '{phase, stats, genesis, peers: .peers[:5]}'

peer object

{
  "id": "node_macmini",
  "label": "MacNode",
  "class": "S",
  "region": "NA-W",
  "status": "offline",
  "role": "peer",
  "joinedAt": "2026-07-17T17:04:12.138Z",
  "lastSeen": "2026-07-18T04:14:57.178Z",
  "lat": 37.5,
  "lng": -122.5
}

Run the P2P peer

bash

# Genesis bootstrap is automatic
grid peer --name garage --with-bench

# Bind a different local listener
grid peer --name garage --listen 0.0.0.0:9901

# Add a known peer without removing Genesis
grid peer --name garage --connect peer.example:9900

The P2P protocol performs an authenticated hello, ping/pong RTT measurement, peer gossip, signed-truth refresh, ban enforcement, and block replication. The canonical Genesis endpoint is omitted only with --no-genesis, which is intended for controlled testing or the Genesis host itself.

bash

# All-in-one node: P2P peer + host + mine
grid node

# Optional P2P overrides
grid node --p2p-listen 0.0.0.0:9901 --p2p-connect peer.example:9900

Public map status is live data. A non-Genesis peer is marked offline when its location heartbeat is more than 60 seconds old. Genesis status comes from an HTTPS health check, not a stale map record.

Mesh ping (write)

POST/api/mesh/ping

Ed25519-signed, location-only heartbeat. The body is strictly allowlisted and replay-protected.

GET/api/mesh/ping

Machine-readable schema: accepted fields, filters, auth header name.

POST body

Field	Required	Notes
version	yes	Protocol version 1
publicKey	yes	32-byte lowercase Ed25519 public key
issuedAtMs / nonce	yes	Fresh timestamp + 16 random bytes
latE4 / lngE4	yes	WGS84 × 10,000; quantized publicly
label / class / region / status	yes	Strictly validated
signature	yes	64-byte Ed25519 signature over canonical body

bash

# The CLI owns canonical serialization, nonces, and signatures.
GRID_GLOBE_LAT=37.7
GRID_GLOBE_LNG=-122.4
GRID_GLOBE_REGION=NA-W
grid init --name garage --class S
grid node

Server filters

Allowlist keys only
Max body ~4 KB
No IPs, hostnames, nested objects
Label sanitized against HTML/script patterns

A successful ping does not register a name on registry.grid. Listing requires paid activation. Globe coordinates should be operator-configured — never reverse-DNS or IP-geolocate silently.

CLI

With opt-in globe coordinates set, the node signs pings automatically. Its private heartbeat key never leaves the machine.

bash

# ~/.grid/env (operator machine only)
GRID_SITE_URL=https://grid-compute.com
GRID_GLOBE_LAT=37.7
GRID_GLOBE_LNG=-122.4
GRID_GLOBE_REGION=NA-W