Implementing Hub & Validator

[parthjadhao01]

Feature: Hub & Validator Architecture for Decentralized Uptime Monitoring

Overview

This issue describes the architecture and communication protocol between the two core components of the decentralized uptime monitoring platform: the Hub and the Validator. This serves as the implementation reference for both nodes.

---

Architecture

Hub

• Central orchestrator node
• Tells validators which websites to monitor
• Connected to a persistent database (stores validator registry, website targets, uptime logs)
• Communicates with validators over WebSocket

Validator

• Distributed worker node
• Receives website check requests from the Hub
• Performs uptime validation and reports results back to the Hub
• Communicates with the Hub over WebSocket

---

System Architecture Diagram

---

Communication Protocol

All Hub ↔ Validator communication happens over WebSocket. Since multiple requests and responses can be in-flight simultaneously, a callback-based system is used to match each response to its originating request.

Callback-Based Request/Response

Every outgoing request includes a unique callbackId. Both Hub and Validator maintain a callback registry — an object that maps callbackId → handler function. When a response arrives, it carries the same callbackId, which is used to look up and invoke the corresponding handler.

sequenceDiagram
    participant V as Validator
    participant H as Hub

    V->>H: Request { callbackId: "abc123", type: "signup", ... }
    Note over V: Store callback["abc123"] = handleSignupResponse
    H-->>V: Response { callbackId: "abc123", validatorId: "v_001" }
    Note over V: Invoke callback["abc123"](response) → clears entry

Loading

Callback Object Structure (both Hub & Validator):

const callbacks = {
  "abc123": (response) => { /* handle response */ },
  "xyz789": (response) => { /* handle response */ },
}

---

Stage 1 — Validator Registration Flow

When a validator node comes online, it initiates contact with the Hub to register itself.

sequenceDiagram
    participant V as Validator
    participant H as Hub
    participant DB as Database

    V->>H: SIGNUP { callbackId, publicKey, signature }
    Note over H: Verify signature using publicKey
    H->>DB: Store validator (status: active)
    DB-->>H: Confirmed
    H-->>V: { callbackId, validatorId }
    Note over V: Store validatorId locally

Loading

Step-by-Step

Step	Actor	Action
1	Validator	Sends a signup message to Hub with callbackId, publicKey, and a cryptographic signature
2	Hub	Verifies the signature against the provided publicKey
3	Hub	Registers the validator in the database with status active (skips insert if already registered)
4	Hub	Responds with the assigned validatorId, matched via callbackId
5	Validator	Stores the received validatorId and is now ready to accept tasks

---

Stage 2 — Website Uptime Check Flow

Once registered, validators receive website check requests from the Hub and report results back.

sequenceDiagram
    participant H as Hub
    participant V as Validator
    participant W as Target Website

    H->>V: CHECK_REQUEST { callbackId, url, checkId }
    Note over V: Store callback[callbackId] = handleResult
    V->>W: HTTP GET / HEAD
    W-->>V: Response (status, latency)
    V->>H: CHECK_RESULT { callbackId, status, latency, timestamp }
    Note over H: Invoke callback[callbackId](result)
    H->>DB: Store uptime record

Loading

---

Validator Authentication Details

Validators authenticate using asymmetric cryptography to prevent spoofing.

Field	Description
publicKey	Validator's public key, sent during signup
signature	A signed payload (e.g., signed timestamp or nonce) using the validator's private key
callbackId	Unique ID for correlating the response to this signup request

The Hub verifies the signature server-side before persisting anything to the database. If verification fails, the signup is rejected.

---

Database Schema (Proposed)

validators table

Column	Type	Description
id	UUID / string	Auto-generated validator ID
public_key	string	Validator's public key
status	enum	active | inactive
registered_at	timestamp	When the validator first registered
last_seen	timestamp	Last WebSocket ping/activity

---

Acceptance Criteria

• Validator can connect to Hub via WebSocket
• Validator sends signed signup request on connect
• Hub verifies signature and stores validator in DB
• Hub responds with validatorId via callback
• Hub can dispatch website check requests to active validators
• Validators return check results (status code, latency, timestamp)
• Callback registry correctly maps responses to pending requests
• Duplicate validator registration is handled gracefully (upsert / re-auth)

---

Labels

architecture feature validator hub websocket auth core