Skip to main content

GhostCloakClient

Manages TLS relay sessions for address unlinkability. Connects to the relay server via WebSocket and proxies all Midnight node requests.

Import​

import { GhostCloakClient } from '@knight-shield/core';

Constructor​

const client = new GhostCloakClient(relayUrl);
// e.g., 'wss://relay.nightshield.app:8443'

Methods​

startSession(): Promise<RelaySession>​

Opens a WebSocket connection and creates a new relay session.

const session = await client.startSession();
// {
//   sessionId: string,
//   startedAt: Date,
//   isActive: true,
//   relayUrl: string
// }

Timeout: 10 seconds for connection establishment.

stopSession(): Promise<void>​

Sends a session_end message and closes the WebSocket connection.

await client.stopSession();

proxyRequest(payload): Promise<any>​

Sends a request through the relay to the Midnight node and returns the response.

const response = await client.proxyRequest({
  method: 'getBalance',
  params: { address: '0x...' }
});

Timeout: 30 seconds for proxy requests.

Session State​

client.sessionId;   // Current session ID (or undefined)
client.isActive;    // Whether a session is currently active
client.relayUrl;    // Configured relay server URL

Message Protocol​

The client communicates with the relay server using JSON messages over WebSocket:

// Session start
{ type: 'session_start', sessionId: '...' }

// Proxy request
{ type: 'proxy', sessionId: '...', payload: { ... } }

// Proxy response (from relay)
{ type: 'proxy_response', sessionId: '...', payload: { ... } }

// Session end
{ type: 'session_end', sessionId: '...' }

Error Handling​

  • Connection timeouts throw after 10 seconds
  • Proxy request timeouts throw after 30 seconds
  • Network errors close the session and set isActive = false
  • Starting a session while one is active automatically stops the previous session