Does web3.js v4 retain built-in WebSocket reconnection logic, or is it entirely delegated to the application layer?

Reconnection Logic in web3.js v4

In web3.js v4, built-in automatic WebSocket reconnection logic is not retained within the core Provider abstraction. Connection lifecycle management, including reconnection and the restoration of subscriptions, is now delegated to the application layer or the specific transport implementation.

Explanation of the Shift

The transition from v1.x to v4 involved a restructuring of the provider architecture to align with EIP-1193. In v1.x, the WebSocketProvider acted as a monolithic entity that handled certain socket states implicitly. In v4, the library has moved toward modular transports. This means the high-level Web3 instance no longer monitors the underlying socket's health or automatically attempts to re-establish a dropped connection.

Because the Web3 object is now a wrapper around a provider, it does not possess the internal state necessary to trigger a reconnect. Consequently, if a WebSocket connection drops, the application will not automatically recover, and any active subscriptions will be lost until the application manually reinstantiates the provider and re-subscribes to the required events.

Migration and Implementation Steps

To maintain the stability of WebSocket connections when migrating from v1.x to v4, implement the following pattern:

• Maintain Provider References: Store a direct reference to the provider instance. Methods like .clearSubscriptions() are scoped to the provider, not the global web3 object.
• Implement a Heartbeat: Use a periodic eth_blockNumber or similar lightweight call to detect connection timeouts.
• Manual Re-initialization: Upon detecting a disconnect, dispose of the existing provider and create a new instance.
• Subscription Recovery: Maintain a registry of active subscriptions in your application state to programmatically re-subscribe after a successful reconnection.

Verification

To verify the lack of built-in reconnection in your current environment, you can perform this scoped test:

// 1. Initialize Web3 v4 with a WebSocket provider
// 2. Manually terminate the WebSocket server or block the port
// 3. Attempt a provider call or observe the subscription stream
// Result: The client will not attempt to reconnect automatically.

Diagnostic Detail Required: Are you utilizing a third-party transport wrapper or a specific node provider (e.g., Infura, Alchemy) that may provide its own reconnection middleware outside of the web3.js library?