Skip to content

TECHNICAL_GUIDE.md

Latest commit

 

History

History
1026 lines (824 loc) · 23.8 KB

TECHNICAL_GUIDE.md

File metadata and controls

1026 lines (824 loc) · 23.8 KB
Raw

Hypergraph Hypernode - Technical Integration Guide

Version: 2.0.0 Last Updated: 2025-01-31 Audience: Developers, System Architects, DevOps Engineers

Table of Contents

  1. Architecture Overview
  2. Factory Handshake Protocol
  3. Hypergraph Metacluster Integration
  4. Fabrik Gating System
  5. Service Mesh & Networking
  6. Security Model
  7. API Integration
  8. Deployment Patterns
  9. Performance Tuning
  10. Monitoring & Observability

Architecture Overview

System Layers

┌─────────────────────────────────────────────────────────────┐
│                     Public Internet Layer                   │
│  HTTPS (443), WebSocket (WSS), WireGuard VPN (51820/UDP)   │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                   Ingress & Security Layer                  │
│         Nginx → TLS Termination → Rate Limiting             │
│         → Ed25519 Signature Validation → Firewall           │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                    Authentication Layer                     │
│    API Gateway → JWT Validation → Fabrik Gates Check       │
│    → Resource Authorization → Consent Verification          │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                  Service Orchestration Layer                │
│   Docker Swarm Overlay Network (hypergraph_overlay)        │
│   → Service Discovery (DNS) → Load Balancing                │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                   Application Services Layer                │
│  Hypergraph Lab │ Semantic Lab │ Ledger Bridge │ Storage   │
│  Graph Service │ Model Gateway │ Data Rhizome │ Keymanager │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                     Data & State Layer                      │
│    Redis (cache/pubsub) │ MongoDB (persistence)            │
│    MinIO (objects) │ Ceph (distributed storage)            │
└─────────────────────────────────────────────────────────────┘

Component Interactions

sequenceDiagram
    participant User
    participant Nginx
    participant APIGateway
    participant Factory
    participant Hypergraph
    participant Service

    User->>Nginx: HTTPS Request
    Nginx->>APIGateway: Forward with TLS
    APIGateway->>Factory: Validate Signature
    Factory-->>APIGateway: Signature Valid
    APIGateway->>Hypergraph: Check Peer Status
    Hypergraph-->>APIGateway: Peer Active
    APIGateway->>Service: Route Request
    Service-->>APIGateway: Response
    APIGateway-->>Nginx: Response
    Nginx-->>User: HTTPS Response
Loading

Factory Handshake Protocol

Registration Flow

Step 1: Node Generates Identity

# Generate Ed25519 keypair
openssl genpkey -algorithm Ed25519 -out node.key
openssl pkey -in node.key -pubout -out node.pub

# Generate self-signed certificate
openssl req -new -x509 -key node.key -out node.crt -days 3650 \
  -subj "/CN=hypergraph-node-<NODE_ID>"

Step 2: Node Sends Registration Request

POST /api/factory/register
Host: factory.hypergraph.dev
Content-Type: application/json
X-Signature: <base64-encoded-signature>

{
  "nodeId": "550e8400-e29b-41d4-a716-446655440000",
  "publicKey": "MCowBQYDK2VwAyEA...",
  "capabilities": ["gpu", "storage", "compute"],
  "location": "eu-west-1",
  "timestamp": "2025-01-31T12:00:00Z",
  "version": "2.0.0"
}

Signature Generation:

# Create signature
echo -n "$PAYLOAD" | openssl dgst -sha256 -sign node.key | base64 -w0

Step 3: Factory Validates and Responds

{
  "success": true,
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIB...\n-----END CERTIFICATE-----",
  "hypergraphAddress": "10.88.0.42",
  "bootstrapPeers": ["10.88.0.1", "10.88.0.2", "10.88.0.3"],
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-01-31T12:00:00Z"
}

Step 4: Node Configures VPN and Joins Hypergraph

# Configure WireGuard with assigned IP
cat > /etc/wireguard/wg0.conf <<EOF
[Interface]
PrivateKey = <node-wg-private-key>
Address = 10.88.0.42/16
ListenPort = 51820

[Peer]
PublicKey = <bootstrap-peer-pubkey>
Endpoint = 10.88.0.1:51820
AllowedIPs = 10.88.0.0/16
PersistentKeepalive = 25
EOF

# Start VPN
wg-quick up wg0

Step 5: Node Joins Hypergraph Metacluster

POST /api/hypergraph/join
Host: factory.hypergraph.dev
Authorization: Bearer <factory-token>
X-Signature: <base64-encoded-signature>

{
  "nodeId": "550e8400-e29b-41d4-a716-446655440000",
  "certificate": "<factory-issued-cert-base64>",
  "capabilities": ["gpu", "storage", "compute"],
  "signature": "<ed25519-signature>"
}

Response:

{
  "success": true,
  "peers": [
    {
      "nodeId": "peer-1-uuid",
      "vpnAddress": "10.88.0.1",
      "capabilities": ["bootstrap", "storage"],
      "reputation": 98
    },
    ...
  ],
  "consensusRules": {
    "minPeers": 3,
    "quorumThreshold": 0.67,
    "voteTimeout": 30
  },
  "tribe": "default"
}

Certificate Validation

Factory certificates are X.509 v3 certificates with custom extensions:

X509v3 extensions:
    X509v3 Subject Alternative Name:
        URI:hypergraph://node/<node-id>
    X509v3 Key Usage:
        Digital Signature, Key Encipherment
    X509v3 Extended Key Usage:
        TLS Web Client Authentication
    hypergraph.capabilities:
        gpu, storage, compute
    hypergraph.tribe:
        default

Validation Code Example:

from cryptography import x509
from cryptography.hazmat.backends import default_backend

def validate_factory_certificate(cert_pem):
    cert = x509.load_pem_x509_certificate(cert_pem.encode(), default_backend())

    # Check issuer
    issuer = cert.issuer.rfc4514_string()
    if "O=Hypergraph Factory" not in issuer:
        raise ValueError("Invalid issuer")

    # Check expiration
    if cert.not_valid_after < datetime.now():
        raise ValueError("Certificate expired")

    # Extract node ID from SAN
    san = cert.extensions.get_extension_for_oid(
        x509.oid.ExtensionOID.SUBJECT_ALTERNATIVE_NAME
    )
    node_uri = next(
        (uri.value for uri in san.value if uri.value.startswith("hypergraph://node/")),
        None
    )

    if not node_uri:
        raise ValueError("No node URI in certificate")

    node_id = node_uri.split("/")[-1]
    return node_id

Hypergraph Metacluster Integration

Consensus Participation

Hypernodes participate in distributed consensus for:

  • Peer admission/eviction
  • Resource allocation
  • Consent-gated operations
  • Network policy updates

Consensus Algorithm: Byzantine Fault Tolerant (BFT) variant

Quorum Calculation:

Quorum = ceil(N * threshold)
where:
  N = total active peers
  threshold = 0.67 (configurable)

Vote Message Format:

{
  "epoch": 12345,
  "proposal": {
    "type": "peer_admission",
    "nodeId": "new-peer-uuid",
    "capabilities": ["storage"]
  },
  "vote": "approve",
  "voterId": "my-node-uuid",
  "signature": "<ed25519-signature>",
  "timestamp": "2025-01-31T12:00:00Z"
}

Peer Discovery & Reputation

Reputation Score (0-100):

  • Initial: 50
  • Uptime contribution: +1 per 24h online
  • Successful consensus: +0.5 per vote
  • Failed health check: -5
  • Byzantine behavior: -50 (with peer review)

Peer Discovery Protocol:

# Broadcast presence every 60 seconds
def broadcast_presence():
    message = {
        "nodeId": NODE_ID,
        "vpnAddress": VPN_ADDRESS,
        "capabilities": CAPABILITIES,
        "reputation": get_reputation_score(),
        "timestamp": datetime.utcnow().isoformat(),
        "signature": sign_message(message)
    }

    # Send to DHT
    dht.put(f"peer:{NODE_ID}", message, ttl=120)

    # Multicast to local subnet
    multicast_send("239.255.0.1", 5000, message)

Fabrik Gating System

Role Hierarchy

roles:
  admin:
    inherits: []
    permissions:
      - "*:*"  # All permissions

  operator:
    inherits: ["user"]
    permissions:
      - "service:start"
      - "service:stop"
      - "service:restart"
      - "service:logs"
      - "node:status"

  builder:
    inherits: ["user"]
    permissions:
      - "image:build"
      - "image:deploy"
      - "deploy:staging"

  security:
    inherits: ["user"]
    permissions:
      - "yubikey:*"
      - "keys:rotate"
      - "audit:view"

  user:
    inherits: ["guest"]
    permissions:
      - "api:read"
      - "api:write"
      - "storage:read"
      - "storage:write"
      - "user:self"

  guest:
    inherits: []
    permissions:
      - "api:read"
      - "public:*"

Tribe System

Tribe Definition:

tribes:
  - name: "core"
    description: "Core infrastructure team"
    roles: ["admin", "operator"]
    gates:
      - "hypergraph:write"
      - "factory:admin"
      - "consensus:vote"
    members:
      - nodeId: "admin-node-1"
        role: "admin"
      - nodeId: "operator-node-1"
        role: "operator"

  - name: "builders"
    description: "Build and deployment team"
    roles: ["builder", "reviewer"]
    gates:
      - "image:build"
      - "deploy:staging"
      - "deploy:review"
    members:
      - nodeId: "builder-node-1"
        role: "builder"

  - name: "public"
    description: "Public access"
    roles: ["guest", "user"]
    gates:
      - "api:read"
      - "storage:read"
    members: []  # Open membership

Resource Gate Implementation

Gate Definition:

{
  "id": "hypergraph:write",
  "description": "Write operations to hypergraph",
  "requireAuth": true,
  "allowedRoles": ["admin", "operator"],
  "allowedTribes": ["core"],
  "requireConsent": true,
  "consentConfig": {
    "minPeers": 2,
    "timeout": 300,
    "quorum": 0.67
  },
  "rateLimit": {
    "requests": 10,
    "window": 60
  },
  "audit": true
}

Gate Check Algorithm:

def check_gate(user, gate_id, request):
    gate = get_gate(gate_id)

    # 1. Authentication check
    if gate.requireAuth and not user.authenticated:
        raise Unauthorized("Authentication required")

    # 2. Role check
    if user.role not in gate.allowedRoles:
        raise Forbidden("Insufficient role")

    # 3. Tribe check
    if user.tribe not in gate.allowedTribes:
        raise Forbidden("Tribe not allowed")

    # 4. Rate limit check
    if is_rate_limited(user, gate):
        raise TooManyRequests("Rate limit exceeded")

    # 5. Consent check (if required)
    if gate.requireConsent:
        consent = request.get("consent")
        if not validate_consent(consent, gate.consentConfig):
            raise Forbidden("Insufficient consent")

    # 6. Audit log
    if gate.audit:
        log_access(user, gate_id, request)

    return True

Consent Gating Protocol

Consent Token Structure:

{
  "token": "lab-epoch-001",
  "peers": [
    {
      "nodeId": "peer-a-uuid",
      "publicKey": "MCowBQYDK2VwAyEA...",
      "signature": "<peer-a-signature>",
      "timestamp": "2025-01-31T12:00:00Z"
    },
    {
      "nodeId": "peer-b-uuid",
      "publicKey": "MCowBQYDK2VwAyEA...",
      "signature": "<peer-b-signature>",
      "timestamp": "2025-01-31T12:00:05Z"
    }
  ],
  "threshold": 2,
  "authority": {
    "name": "admin",
    "nodeId": "admin-node-uuid",
    "signature": "<authority-signature>"
  },
  "expiresAt": "2025-01-31T12:05:00Z"
}

Consent Validation:

def validate_consent(consent, config):
    # Check expiration
    if datetime.fromisoformat(consent["expiresAt"]) < datetime.utcnow():
        return False

    # Check threshold
    if len(consent["peers"]) < config["minPeers"]:
        return False

    # Verify peer signatures
    for peer in consent["peers"]:
        if not verify_peer_signature(peer):
            return False

    # Verify authority signature
    if not verify_authority_signature(consent["authority"]):
        return False

    # Check quorum
    active_peers = get_active_peers()
    quorum = len(consent["peers"]) / len(active_peers)
    if quorum < config["quorum"]:
        return False

    return True

Service Mesh & Networking

Docker Swarm Overlay Network

Network Creation:

docker network create \
  --driver overlay \
  --attachable \
  --subnet 10.89.0.0/16 \
  --opt encrypted \
  hypergraph_overlay

Service Registration:

version: '3.8'

services:
  api-gateway:
    image: hypergraph/api-gateway:latest
    networks:
      - hypergraph_overlay
    deploy:
      replicas: 3
      placement:
        constraints:
          - node.role == worker
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure

Service Discovery

DNS Resolution:

  • Services resolve via Docker's embedded DNS: http://api-gateway:8000
  • VIP (Virtual IP) load balancing across replicas
  • Health-based routing

Custom Service Registry (optional):

# Register service in Redis
def register_service(name, host, port):
    redis.hset(f"service:{name}", "host", host)
    redis.hset(f"service:{name}", "port", port)
    redis.expire(f"service:{name}", 60)

# Heartbeat
def heartbeat():
    while True:
        register_service("my-service", "10.89.0.42", 8080)
        time.sleep(30)

Load Balancing

Nginx Upstream:

upstream api_gateway {
    least_conn;
    server api-gateway-1:8000 max_fails=3 fail_timeout=30s;
    server api-gateway-2:8000 max_fails=3 fail_timeout=30s;
    server api-gateway-3:8000 max_fails=3 fail_timeout=30s;
}

server {
    listen 443 ssl http2;
    server_name *.hypergraph.dev;

    location /api {
        proxy_pass http://api_gateway;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Rate limiting
        limit_req zone=api burst=20 nodelay;

        # Timeout
        proxy_connect_timeout 5s;
        proxy_send_timeout 30s;
        proxy_read_timeout 30s;
    }
}

Security Model

Threat Model

Threats Addressed:

  1. Impersonation: Ed25519 signatures prevent fake nodes
  2. MITM: TLS 1.3 + certificate pinning
  3. Replay Attacks: Timestamp validation (5-minute window)
  4. DoS: Rate limiting + firewall
  5. Byzantine Peers: Reputation system + peer voting
  6. Privilege Escalation: Fabrik gates + least-privilege

Attack Surface:

  • Public: Nginx (port 443), WireGuard (port 51820/UDP)
  • VPN Only: All internal services
  • Local Only: Docker socket, database ports

Encryption

In Transit:

  • TLS 1.3 for HTTPS/WSS
  • WireGuard ChaCha20-Poly1305 for VPN
  • Docker Swarm overlay encryption (AES-GCM)

At Rest:

  • MinIO server-side encryption (SSE-S3)
  • MongoDB encryption at rest (WiredTiger)
  • Encrypted Docker volumes (LUKS)

Key Management

Key Hierarchy:

Master Key (LUKS)
  ├── Node Identity Key (Ed25519)
  │     ├── Factory Certificate
  │     └── Peer Signatures
  ├── WireGuard VPN Key (Curve25519)
  ├── TLS Private Key (RSA 4096 or ECDSA P-384)
  └── Service Keys
        ├── JWT Signing Key (HMAC-SHA256)
        ├── Encryption Key (AES-256)
        └── Database Encryption Key (AES-256)

Key Rotation:

# Rotate node identity key
hypergraph security rotate-keys

# Steps:
# 1. Generate new Ed25519 keypair
# 2. Re-register with Factory
# 3. Announce key change to peers
# 4. Wait for peer acknowledgments (grace period: 24h)
# 5. Deactivate old key
# 6. Update all service configurations

API Integration

REST API

Base URL: https://<node-id>.hypergraph.dev/api

Authentication:

# Login
curl -X POST https://node.hypergraph.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"user","password":"pass"}'

# Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "...",
  "expiresIn": 86400
}

# Use token
curl -H "Authorization: Bearer <token>" \
  https://node.hypergraph.dev/api/protected/resource

Common Endpoints:

GET    /api/v1/status              # Node health
GET    /api/v1/peers               # Connected peers
POST   /api/v1/semantic/playground # NLP analysis
POST   /api/v1/hypergraph-lab/*    # Consent-gated inference
GET    /api/v1/storage/list        # List stored files
POST   /api/v1/storage/upload      # Upload file

WebSocket API

Connection:

const ws = new WebSocket('wss://node.hypergraph.dev/ws');

ws.onopen = () => {
  // Authenticate
  ws.send(JSON.stringify({
    type: 'auth',
    token: '<jwt-token>'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

// Subscribe to events
ws.send(JSON.stringify({
  type: 'subscribe',
  channels: ['peers', 'consensus', 'metrics']
}));

Event Types:

// Peer joined
{
  "type": "peer_joined",
  "data": {
    "nodeId": "new-peer-uuid",
    "vpnAddress": "10.88.0.50",
    "capabilities": ["storage"]
  },
  "timestamp": "2025-01-31T12:00:00Z"
}

// Consensus vote
{
  "type": "consensus_vote",
  "data": {
    "proposal": "peer_admission",
    "votes": {"approve": 5, "reject": 1},
    "status": "pending"
  },
  "timestamp": "2025-01-31T12:01:00Z"
}

// Metrics update
{
  "type": "metrics",
  "data": {
    "cpu": 45.2,
    "memory": 68.5,
    "disk": 32.1,
    "network": {
      "rx_bytes": 1024000,
      "tx_bytes": 512000
    }
  },
  "timestamp": "2025-01-31T12:02:00Z"
}

Deployment Patterns

High Availability (HA)

Multi-Node Cluster:

Manager Node 1 (10.88.0.1)
  ├── api-gateway (leader)
  ├── graph (primary)
  └── storage-hub (primary)

Manager Node 2 (10.88.0.2)
  ├── api-gateway (replica)
  ├── graph (replica)
  └── storage-hub (replica)

Worker Node 3 (10.88.0.3)
  ├── hypergraph-lab
  ├── semantic-lab
  └── model-gateway

Worker Node 4 (10.88.0.4)
  ├── ledger-bridge
  ├── keymanager
  └── data-rhizome

Failover:

  • Swarm manager quorum: 3 managers for 2N+1 fault tolerance
  • Service replicas: 3 for critical services
  • Health checks: HTTP probe every 10s, 3 retries
  • Auto-restart: on-failure with exponential backoff

Blue-Green Deployment

# Deploy green version
docker service create --name api-gateway-green \
  --network hypergraph_overlay \
  --replicas 3 \
  hypergraph/api-gateway:2.1.0

# Test green
curl http://api-gateway-green:8000/health

# Switch traffic (update Nginx upstream)
nginx -s reload

# Remove blue
docker service rm api-gateway-blue

Canary Deployment

# 90% traffic to stable, 10% to canary
services:
  api-gateway-stable:
    deploy:
      replicas: 9
      labels:
        version: "2.0.0"

  api-gateway-canary:
    deploy:
      replicas: 1
      labels:
        version: "2.1.0"

Performance Tuning

System Configuration

# Increase file descriptors
echo "* soft nofile 65536" >> /etc/security/limits.conf
echo "* hard nofile 65536" >> /etc/security/limits.conf

# Tune network stack
cat >> /etc/sysctl.conf <<EOF
net.core.somaxconn = 1024
net.ipv4.tcp_max_syn_backlog = 2048
net.ipv4.ip_local_port_range = 10000 65535
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_fin_timeout = 15
EOF

sysctl -p

Docker Optimization

// /etc/docker/daemon.json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "storage-driver": "overlay2",
  "dns": ["8.8.8.8", "8.8.4.4"],
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 64000,
      "Soft": 64000
    }
  }
}

Service Optimization

Redis:

# redis.conf
maxmemory 2gb
maxmemory-policy allkeys-lru
tcp-backlog 511
timeout 300
tcp-keepalive 60

MongoDB:

# mongod.conf
storage:
  wiredTiger:
    engineConfig:
      cacheSizeGB: 4
net:
  maxIncomingConnections: 1000

Monitoring & Observability

Prometheus Metrics

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'hypergraph-nodes'
    static_configs:
      - targets: ['10.88.0.1:9090', '10.88.0.2:9090']

  - job_name: 'services'
    dns_sd_configs:
      - names: ['_prometheus._tcp.hypergraph_overlay']

Custom Metrics:

from prometheus_client import Counter, Histogram, Gauge

# Define metrics
requests_total = Counter('api_requests_total', 'Total API requests', ['method', 'endpoint', 'status'])
request_duration = Histogram('api_request_duration_seconds', 'Request duration')
peers_connected = Gauge('hypergraph_peers_connected', 'Number of connected peers')

# Instrument
@request_duration.time()
def handle_request(method, endpoint):
    # Process request
    result = process(method, endpoint)

    # Record
    requests_total.labels(method=method, endpoint=endpoint, status=result.status).inc()

    return result

Grafana Dashboards

Hypernode Overview:

  • CPU, Memory, Disk usage
  • Network I/O
  • Service health
  • Active peers
  • Consensus participation

Hypergraph Network:

  • Peer map (geographic)
  • Reputation scores
  • Consensus timeline
  • Transaction throughput

Appendix

Glossary

  • Hypernode: An authenticated node in the Hypergraph network
  • Factory: Central registration and certificate authority
  • Metacluster: The distributed hypergraph consensus network
  • Fabrik: Access control system based on roles and tribes
  • Consent Gating: Peer-approved sensitive operations
  • Tribe: Organizational unit with shared access permissions

References

End of Technical Guide