Clearnode WebSocket Connection - Frequently Asked Questions

[nksazonov]

Clearnode WebSocket Connection

WebSocket connections in Clearnode provide real-time, bidirectional communication between clients and the server. These persistent connections enable immediate message delivery, automatic balance updates, and efficient RPC communication. However, like all network connections, WebSocket connections can occasionally drop due to network issues, timeouts, or server-side constraints.

❓ Why do WebSocket connections drop?

WebSocket connections can drop for several reasons:

• Write timeouts: If the server cannot send a message to the client within 5 seconds (the default defaultRPCMessageWriteDuration), the connection will be automatically closed to prevent resource exhaustion
• Network interruptions: Temporary network issues, proxy timeouts, or ISP problems
• Client inactivity: Extended periods without any communication may trigger connection cleanup
• Server maintenance: Planned or unplanned server restarts and deployments

When a connection drops due to a write timeout, you'll typically see an error message like:
"websocket: close 1006 (abnormal closure): unexpected EOF"

❓ How should I handle dropping connections?

There are two main strategies for dealing with connection drops:

Option 1: Continuous Pinging

Implement regular calls that invoke the Clearnode's ping endpoint to keep the connection alive and detect drops early:

// Send ping every 30 seconds
const pingInterval = setInterval(() => {
  if (websocket.readyState === WebSocket.OPEN) {
    // Send ping using the Clearnode ping method
    const pingMessage = {
      "req": [Date.now(), "ping", {}, Date.now()],
      "sig": ["your_signature"]
    };
    websocket.send(JSON.stringify(pingMessage));
  }
}, 30000);

Benefits:

• Maintains persistent connection
• Immediate message delivery
• Real-time balance and channel updates
• Lower latency for frequent operations

Option 2: Connect on Demand

Establish connections only when needed and authenticate fresh each time:

async function connectAndAuth() {
  const ws = new WebSocket('wss://clearnet.yellow.com/ws');

  // Perform full authentication flow
  await authenticate(ws);

  // Use connection for your operation
  await performOperation(ws);

  // Close when done
  ws.close();
}

Benefits:

• Reduced resource usage
• No connection maintenance overhead
• Always fresh authentication state
• Suitable for infrequent operations

Recommendation: Use continuous pinging for applications requiring real-time updates (trading bots, games), and connect on demand for occasional operations (simple transfers, balance checks).