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()

URL

Type: string
Optional

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

Type: time.Duration
Default: 10s
Optional

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

Type: int
Default: 3
Optional

Maximum number of retry attempts for retryable errors.

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

RetryDelay

Type: time.Duration
Default: 150ms
Optional

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

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

Keep-alive ping configuration.

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

KeepAlive.Enabled

Type: bool
Default: true
Optional

Whether keep-alive pings are enabled.

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

KeepAlive.Interval

Type: time.Duration
Default: 30s
Optional

Interval between keep-alive pings.

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

Reconnect

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

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

Type: bool
Default: true
Optional

Whether reconnection is enabled.

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

Reconnect.MaxAttempts

Type: int
Default: 5
Optional

Maximum reconnection attempts.

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

Reconnect.Delay

Type: time.Duration
Default: 2s
Optional

Delay between reconnection attempts.

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

Methods

Type: *transport.MethodFilter
Optional

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

Type: []string
Optional

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

Type: []string
Optional

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

Type: string
Default: "webSocket"
Optional

Transport identifier key.

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

Name

Type: string
Default: "WebSocket JSON-RPC"
Optional

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.

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

tr := transport.WebSocket("wss://eth.llamarpc.com", transport.WebSocketTransportConfig{ Timeout: 5 * time.Second, }) publicClient, err := client.CreatePublicClient(client.PublicClientConfig{ Transport: tr, })

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

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

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