Relay Server

The relay server is a Node.js TLS proxy that decouples wallet identity from Midnight node connections. It powers the GhostCloak feature.

Source

packages/relay-server/src/

Architecture

Mobile App ──WebSocket (TLS)──→ Relay Server ──WebSocket──→ Midnight Node
                                     │
                                SessionManager
                                     │
                                 Monitoring

Server

File: server.ts

The server uses the ws library for WebSocket connections:

• Port: 8443 (configurable via PORT env var)
• Upstream: Midnight node (configurable via MIDNIGHT_NODE env var, default ws://127.0.0.1:9944)
• Routes:
  • GET /health — JSON health check with active session count
  • WS /relay — WebSocket endpoint for relay sessions

Message Handling

Message Type	Action
session_start	Create session via SessionManager, proxy upstream connection
proxy	Forward payload to upstream Midnight node
session_end	End session, close upstream connection

Session Manager

File: session-manager.ts

Tracks active and ended sessions:

interface Session {
  sessionId: string;
  startedAt: Date;
  endedAt?: Date;
}

Methods

• start(sessionId) — Register a new session
• end(sessionId) — Mark session as ended with timestamp
• getActiveCount() — Number of currently active sessions
• getSession(sessionId) — Lookup session by ID
• cleanup(maxAgeMs) — Remove sessions older than threshold (default: 1 hour)

Monitoring

File: monitoring.ts

Background monitoring started at server launch:

• Cleanup interval: Every 10 minutes — removes stale sessions
• Log interval: Every 60 seconds — reports active sessions, RSS memory, heap usage

startMonitoring(sessionManager);
// Logs: "Active sessions: 3, RSS: 45MB, Heap: 32MB/64MB"

Configuration

Env Variable	Default	Description
PORT	8443	Server listen port
MIDNIGHT_NODE	ws://127.0.0.1:9944	Upstream Midnight node WebSocket URL

Docker

The relay server can be run as a Docker container. A basic Dockerfile:

FROM node:22-slim
WORKDIR /app
COPY packages/relay-server/dist/ ./dist/
COPY packages/relay-server/package.json ./
RUN npm install --production
EXPOSE 8443
CMD ["node", "dist/server.js"]

Health Check

curl http://localhost:8443/health
# { "status": "ok", "activeSessions": 3 }