WebSocket Transport

Persistent connection to Ethereum nodes for real-time subscriptions

The WebSocket transport provides a persistent connection to Ethereum nodes, enabling real-time subscriptions and lower latency for high-frequency requests.

The transport.WebSocket(...) function returns a transport.TransportFactory that you pass into a client config (e.g. client.PublicClientConfig).

Import

import (
  "github.com/ChefBingbong/viem-go/client"
  "github.com/ChefBingbong/viem-go/client/transport"
)

These are the most common imports for using the WebSocket transport:

transport: WebSocket transport factory and config types (e.g. transport.WebSocket, transport.WebSocketTransportConfig).
client: Client constructors/config (e.g. client.CreatePublicClient, client.PublicClientConfig).

Go notes

Transport factories

transport.WebSocket(...) creates a factory, not an immediate connection. The client constructs the transport internally when you create the client.

Closing the client

Close the client when you're done: defer publicClient.Close(). This closes the underlying WebSocket connection.

Usage

publicClient, err := client.CreatePublicClient(client.PublicClientConfig{
  Transport: transport.WebSocket("wss://eth.llamarpc.com"),
})
if err != nil {
  log.Fatal(err)
}
defer publicClient.Close()

Subscriptions (brief)

WebSocket transports support JSON-RPC subscriptions via eth_subscribe.

On a PublicClient, watch actions can choose between polling and subscriptions based on the transport type. See Public Client.

sub, err := publicClient.Subscribe(
  transport.NewHeadsSubscribeParams(),
  func(data json.RawMessage) {
      // ...
  },
  func(err error) {
      // ...
  },
)
if err != nil {
  log.Fatal(err)
}
defer sub.Unsubscribe()

Parameters

URL (optional)

Type: string

The WebSocket RPC endpoint URL.

URL resolution order is:

Function argument: transport.WebSocket(\"wss://...\")
Config: transport.WebSocket(\"\", transport.WebSocketTransportConfig{ URL: \"wss://...\" })
Chain default: params.Chain.RpcUrls[\"default\"].WebSocket[0] (when a client provides a chain)

If no URL can be resolved, client creation fails with transport.ErrURLRequired.

tr := transport.WebSocket("wss://eth.llamarpc.com")

publicClient, err := client.CreatePublicClient(client.PublicClientConfig{
  Transport: tr,
})

Timeout (optional)

Type: time.Duration
Default: 10s

Request timeout for each JSON-RPC call.

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  Timeout: 5 * time.Second,
})

publicClient, err := client.CreatePublicClient(client.PublicClientConfig{
  Transport: tr,
})

RetryCount (optional)

Type: int
Default: 3

Maximum number of retry attempts for retryable errors.

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  RetryCount: 5,
})

RetryDelay (optional)

Type: time.Duration
Default: 150ms

Base delay between retries. Retries use exponential backoff (delay * 2^attempt).

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  RetryDelay: 250 * time.Millisecond,
})

KeepAlive (optional)

Type: *transport.KeepAliveConfig
Default: { Enabled: true, Interval: 30s }

Keep-alive ping configuration.

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  KeepAlive: &transport.KeepAliveConfig{
      Enabled:  true,
      Interval: 30 * time.Second,
  },
})

KeepAlive.Enabled (optional)

Type: bool
Default: true

Whether keep-alive pings are enabled.

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  KeepAlive: &transport.KeepAliveConfig{
      Enabled: false,
  },
})

KeepAlive.Interval (optional)

Type: time.Duration
Default: 30s

Interval between keep-alive pings.

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  KeepAlive: &transport.KeepAliveConfig{
      Enabled:  true,
      Interval: 10 * time.Second,
  },
})

Reconnect (optional)

Type: *transport.ReconnectConfig
Default: { Enabled: true, MaxAttempts: 5, Delay: 2s }

Automatic reconnection configuration.

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  Reconnect: &transport.ReconnectConfig{
      Enabled:     true,
      MaxAttempts: 5,
      Delay:       2 * time.Second,
  },
})

Reconnect.Enabled (optional)

Type: bool
Default: true

Whether reconnection is enabled.

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  Reconnect: &transport.ReconnectConfig{
      Enabled: false,
  },
})

Reconnect.MaxAttempts (optional)

Type: int
Default: 5

Maximum reconnection attempts.

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  Reconnect: &transport.ReconnectConfig{
      Enabled:     true,
      MaxAttempts: 10,
  },
})

Reconnect.Delay (optional)

Type: time.Duration
Default: 2s

Delay between reconnection attempts.

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  Reconnect: &transport.ReconnectConfig{
      Enabled: true,
      Delay:   5 * time.Second,
  },
})

Methods (optional)

Type: *transport.MethodFilter

Restrict which JSON-RPC methods can be called by this transport.

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  Methods: &transport.MethodFilter{
      Include: []string{"eth_subscribe", "eth_unsubscribe"},
      Exclude: []string{"eth_sendTransaction"},
  },
})

Methods.Include (optional)

Type: []string

If set, only methods in Include are allowed (except those blocked by Exclude).

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  Methods: &transport.MethodFilter{
      Include: []string{"eth_subscribe", "eth_unsubscribe"},
  },
})

Methods.Exclude (optional)

Type: []string

Methods to block (checked before Include).

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  Methods: &transport.MethodFilter{
      Exclude: []string{"eth_sendTransaction", "eth_sendRawTransaction"},
  },
})

Key (optional)

Type: string
Default: "webSocket"

Transport identifier key.

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  Key: "foo",
})

Name (optional)

Type: string
Default: "WebSocket JSON-RPC"

Human-readable transport name.

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{
  Name: "Foo WebSocket Transport",
})

Return Type

transport.WebSocket(...) returns a transport.TransportFactory.