⚡ Pitot

Sovereign Lightning Network Health Telemetry & Local Explorer

Pitot is a lightweight, decentralized telemetry daemon and local explorer for the Lightning Network. It replaces the "claimed state" of public gossip with empirically verified, cryptographic ground truth.

---

🎯 The Problem Pitot Solves

In the Lightning Network, public gossip (BOLT #7) only announces that two nodes once created a multisig channel and set fee rates. Gossip cannot tell you if a node is powered on, dropping packets, or completely dead.

When a routing node attempts to forward an HTLC into a dead peer:

1. Payments stall waiting for timeouts.
2. Capital freezes across innocent intermediary hops.
3. Emergency on-chain force-closes trigger when timelocks expire, burning miner fees and locking satoshis in CSV timelock limbo for weeks.

Centralized explorers (1ML, Mempool, Amboss) frequently report dead nodes as "Active" because counterparties are broadcasting closure updates to the graph.

---

⚡ How Pitot Works

Pitot runs locally inside your infrastructure as a sovereign node companion:

1. Cryptographic BOLT #8 Handshakes:
   • Pitot performs fast, non-destructive BOLT #8 Noise_XK handshakes against node endpoints.
   • Because completing Act 2 requires the remote host to compute a shared secret using its actual private key, a successful handshake is mathematical proof that the node daemon is live and responsive.
2. Decentralized Nostr Telemetry Mesh:
   • Nodes running Pitot form a decentralized peer-to-peer telemetry mesh over Nostr using Ephemeral Events (kind: 20051).
   • Probes from multiple geographic vantage points (Europe, America, Asia) are aggregated into a multi-vantage quorum.
   • If a peer drops offline, the mesh reaches consensus in <30 seconds.
3. Zero-Knowledge Privacy:
   • Pitot generates a disposable, rotating Nostr keypair (rotating every 24 hours). It never touches or uses your Lightning node keys.
   • Probing targets are pseudo-randomly sharded—Pitot never exposes your private channel topology.
   • All dashboard queries, route simulations, and node inspections execute 100% locally in-memory. Zero queries leave your machine.
4. Standard SSE / REST Event Stream:
   • Exposes a real-time Server-Sent Events stream (GET /api/v1/events) that local routing bots, dashboards, and automated fee engines can consume to proactively pause routing into dead channels.

---

🚀 Quickstart

Running with Docker / Podman

git clone ssh://git@git.mutatrum.com/mutatrum/pitot.git
cd pitot

# Start the container
docker compose up -d

# Open the dashboard
open http://localhost:8080

---

🔌 API Reference (For Local Tools & Automated Routing)

Pitot exposes a simple, high-performance local REST & SSE API for scripts, dashboards, and automated routing engines:

1. Live Real-Time Event Stream (SSE)

GET /api/v1/events

Subscribes to live Server-Sent Events:

event: peer_status_change
data: {
  "pubkey": "026165850492521f4ac8abd9bd8088123446d126f648ca35e60f88177dc149ceb2",
  "alias": "Boltz",
  "oldStatus": "ONLINE",
  "newStatus": "OFFLINE",
  "latencyMs": null,
  "reportsCount": 4,
  "timestamp": 1789551200
}

2. Query Single Node Health

GET /api/v1/health/:pubkey

Returns:

{
  "pubkey": "026165850492521f...",
  "alias": "Boltz",
  "status": "OFFLINE",
  "last_seen": 1789450000,
  "last_latency_ms": null,
  "consecutive_failures": 5
}

3. Query All Nodes Summary

GET /api/v1/health

---

⚙️ Configuration (config.json)

Copy config.default.json to config.json to customize:

{
  "server": {
    "port": 8080,
    "host": "0.0.0.0"
  },
  "nostr": {
    "relays": [
      "wss://nos.lol",
      "wss://relay.damus.io",
      "wss://relay.primal.net"
    ],
    "ephemeral_kind": 20051,
    "rotate_key_hours": 24
  },
  "prober": {
    "enabled": true,
    "probe_interval_seconds": 60,
    "batch_size": 20,
    "concurrency": 5,
    "timeout_clearnet_ms": 2500,
    "timeout_tor_ms": 6000,
    "tor_proxy": "127.0.0.1:9050"
  }
}

---

🛡️ License

MIT License. Sovereign, open-source software by Mutatrum.