Connection lifecycle

Lasso uses WebSocket ping/pong frames to detect disconnected clients. Keep your client responsive and reconnect when the connection closes.

Connection establishment

Use a standard WebSocket client:

wscat -c 'ws://localhost:4000/ws/rpc/ethereum'

The connection can close when you disconnect, fail to answer heartbeats, encounter a network interruption, or the server restarts. Subscription continuity exhaustion can also close the connection. Core does not authenticate the incoming client; protect this endpoint at your deployment boundary.

Heartbeats

Setting	Value	Behavior
Initial heartbeat	30 seconds	First ping after connecting
Next heartbeat	30 seconds	Scheduled after a pong or the first missed-pong timeout
Pong deadline	5 seconds	Time to answer each ping
Missed-pong tolerance	2 consecutive misses	Connection closes after the second deadline

Most WebSocket libraries, including browsers, automatically answer control-frame pings. You do not need to send JSON-RPC messages to keep the connection alive. Browser JavaScript does not expose ping/pong control frames. A pong resets the missed-heartbeat count. If a client never answers, the nominal timeline is:

0s      Connection opens
30s     Server sends ping #1
35s     No pong: first missed heartbeat
65s     Server sends ping #2
70s     No pong: connection closes

That is approximately 40 seconds from the first unanswered ping, or 70 seconds from a new connection that never responds. Scheduling and network delays can affect the observed times. Lasso answers client-initiated pings with pongs. Those pings do not substitute for answering the server’s own pings.

Idle timeout and session duration

The WebSocket transport has a two-hour idle timeout. It is not a maximum session lifetime: responsive connections can remain open beyond two hours. Traffic, including heartbeat replies, prevents an idle connection from reaching that timeout. Reconnect whenever the connection closes. Do not rely on a periodic two-hour disconnect or a particular idle-timeout close message.

Connection closure

These application-level closure cases have explicit meanings:

Cause	Code	Meaning
Two missed heartbeat replies	1002	`Heartbeat timeout - no pong responses`
Subscription continuity exhausted	1011	`Lasso subscription continuity exhausted`

A JSON-RPC rate-limit error can be returned on an open connection. It does not inherently mean the socket closes with code 1008. Deployments, access changes, proxies, and network failures can produce other close events; handle closure regardless of code. The released Core socket does not promise a dedicated slow-client close code. Bound your own processing and subscription volume, reconnect with capped backoff, and reconcile missed events after any closure.

Reconnection

Reconnect with capped exponential backoff and jitter, then recreate the subscriptions your application still needs. Subscription IDs belong to the old connection and must be replaced with the new IDs returned by eth_subscribe. This Node.js example uses the ws package and subscribes to new heads after each connection:

import WebSocket from 'ws';

const endpoint = process.env.LASSO_WS_URL;
if (!endpoint) throw new Error('Set LASSO_WS_URL to your WebSocket endpoint');
let attempts = 0;
let stopped = false;
let socket;
let retryTimer;
let stableTimer;

function connect() {
  socket = new WebSocket(endpoint);

  socket.on('open', () => {
    // Reset backoff after the connection has remained stable.
    stableTimer = setTimeout(() => { attempts = 0; }, 30_000);
    socket.send(JSON.stringify({
      jsonrpc: '2.0', id: 1, method: 'eth_subscribe', params: ['newHeads']
    }));
  });

  socket.on('message', (data) => {
    const message = JSON.parse(data.toString());
    // Handle subscription acknowledgements, notifications, and RPC errors here.
    console.log(message);
  });

  socket.on('error', () => {
    // The close event owns reconnect scheduling.
  });

  socket.on('close', () => {
    clearTimeout(stableTimer);
    if (stopped) return;
    const ceiling = Math.min(30_000, 1_000 * 2 ** Math.min(attempts++, 5));
    retryTimer = setTimeout(connect, ceiling * (0.5 + Math.random() * 0.5));
  });
}

function stop() {
  stopped = true;
  clearTimeout(retryTimer);
  clearTimeout(stableTimer);
  socket?.close(1000, 'Client shutdown');
}

process.once('SIGINT', stop);
process.once('SIGTERM', stop);
connect();

Recreating a subscription does not replay every event missed while your client was disconnected. Track your last processed block and use historical RPC reads to reconcile gaps where your application requires them.

Subscription cleanup

When your socket closes, Lasso detaches its logical subscriptions and releases their resources. Shared upstream streams can remain open for other clients or internal monitoring; disconnecting one client must not interrupt them. Use eth_unsubscribe when you no longer need an individual subscription. Closing the socket also cleans up its subscriptions; you do not need to wait for asynchronous unsubscribe calls during page unload.

Operating guidance

Let your WebSocket library answer pings promptly; avoid blocking its event loop.
Treat a long gap in notifications separately from a failed connection. A healthy stream may have no matching events.
Track reconnect frequency, subscription errors, and the last processed block.
Expect reconnects during deployments and network changes.
If a profile or provider configuration changes, inspect the active routes before repeatedly retrying.

HTTP API

WebSocket API

Status and metrics

Reference

Releases and evidence

Connection lifecycle

Connection establishment

Heartbeats

Idle timeout and session duration

Connection closure

Reconnection

Subscription cleanup

Operating guidance

​Connection establishment

​Heartbeats

​Idle timeout and session duration

​Connection closure

​Reconnection

​Subscription cleanup

​Operating guidance

Connection establishment

Heartbeats

Idle timeout and session duration

Connection closure

Reconnection

Subscription cleanup

Operating guidance