ws

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 4, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package ws provides the low-level WebSocket transport for Solana JSON-RPC pub/sub notifications. It manages the connection, the read loop, and the subscribe/unsubscribe plumbing. Typed, per-API subscriptions (AccountSubscribe, LogsSubscribe, …) live on *client.Client in the client package.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AccountNotification 

type AccountNotification struct {
	// Slot is the slot at which the update was observed.
	Slot uint64
	// Value is the new account state, or nil if the account was
	// closed or is otherwise absent at the reported slot.
	Value *solana.AccountInfo
}

AccountNotification is a single update delivered to an AccountSubscription.

type AccountSubscription 

type AccountSubscription struct {
	*Subscription
	// contains filtered or unexported fields
}

AccountSubscription is the handle returned by AccountSubscribe. Read notifications from Recv(); stop the subscription with Unsubscribe. Because Recv() is not closed on shutdown, callers should also select on Done() to detect termination.

func (*AccountSubscription) Recv 

func (s *AccountSubscription) Recv() <-chan *AccountNotification

Recv returns the channel that delivers account notifications. The channel is intentionally never closed; detect the end of the subscription via Done() instead.

type BlockFilter 

type BlockFilter struct {
	// All subscribes to every block.
	All bool
	// MentionsAccountOrProgram restricts the subscription to blocks
	// that contain at least one transaction mentioning this
	// account or program.
	MentionsAccountOrProgram solana.PublicKey
}

BlockFilter is the filter passed to BlockSubscribe. Exactly one of All or MentionsAccountOrProgram should be set.

type BlockNotification 

type BlockNotification struct {
	Slot  uint64              `json:"slot"`
	Err   any                 `json:"err"`
	Block *rpc.GetBlockResult `json:"block"`
}

BlockNotification is a single update delivered to a BlockSubscription. Err is non-nil if the server could not reproduce the block for the subscriber; Block is nil in that case. Unlike most subscriptions, Slot here decodes from the value-object directly (the inner slot) rather than from the context envelope.

type BlockSubscription 

type BlockSubscription struct {
	*Subscription
	// contains filtered or unexported fields
}

BlockSubscription is the handle returned by BlockSubscribe.

func (*BlockSubscription) Recv 

func (s *BlockSubscription) Recv() <-chan *BlockNotification

Recv returns the channel that delivers block notifications.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client manages a WebSocket connection to a Solana RPC endpoint and fans out subscription notifications to per-subscription typed channels.

A Client maintains a single underlying WebSocket connection shared by all subscriptions. Construct one with DialWebSocket; call Close to tear down the connection and stop every active subscription.

Client is safe for concurrent use by multiple goroutines.

func DialWebSocket 

func DialWebSocket(ctx context.Context, endpoint string) (*Client, error)

DialWebSocket connects to the given Solana WebSocket RPC endpoint. The endpoint must use the ws:// or wss:// scheme.

func (*Client) AccountSubscribe 

func (c *Client) AccountSubscribe(ctx context.Context, pubkey solana.PublicKey, cfg ...rpc.CommitmentWithEncodingCfg) (*AccountSubscription, error)

AccountSubscribe subscribes to updates for the given account. It returns once the server has acknowledged the subscribe request. Encoding defaults to base64.

func (*Client) BlockSubscribe 

func (c *Client) BlockSubscribe(ctx context.Context, filter BlockFilter, cfg ...rpc.GetBlockCfg) (*BlockSubscription, error)

BlockSubscribe subscribes to block updates matching the filter. This is an unstable RPC method on mainnet; require-explicit-opt-in via --rpc-pubsub-enable-block-subscription on the server.

Encoding defaults to base64, MaxSupportedTransactionVersion to 0, TransactionDetails to "full".

func (*Client) Close 

func (c *Client) Close() error

Close terminates the WebSocket connection and all active subscriptions. It is safe to call Close multiple times.

func (*Client) Codec 

func (c *Client) Codec() jsonrpc.Codec

Codec returns the JSON codec used to encode requests and decode notifications. Typed subscriptions in the client package use it to Unmarshal notification payloads.

func (*Client) Done 

func (c *Client) Done() <-chan struct{}

Done returns a channel that is closed when the client has terminated, either by Close or a fatal connection error.

func (*Client) Endpoint 

func (c *Client) Endpoint() string

Endpoint returns the endpoint URL the client was connected to.

func (*Client) Err 

func (c *Client) Err() error

Err returns the error that terminated the client, or nil if the client is still running or was closed gracefully.

func (*Client) LogsSubscribe 

func (c *Client) LogsSubscribe(ctx context.Context, filter LogsFilter, cfg ...rpc.LogsSubscribeCfg) (*LogsSubscription, error)

LogsSubscribe subscribes to transaction logs matching the given filter.

func (*Client) ProgramSubscribe 

func (c *Client) ProgramSubscribe(ctx context.Context, programID solana.PublicKey, cfg ...rpc.CommitmentWithEncodingCfg) (*ProgramSubscription, error)

ProgramSubscribe subscribes to updates for every account owned by the given program. This is a high-volume subscription for popular programs; always consume promptly or the buffer will drop the oldest notifications. Encoding defaults to base64.

func (*Client) RootSubscribe 

func (c *Client) RootSubscribe(ctx context.Context) (*RootSubscription, error)

RootSubscribe subscribes to root updates. Each notification is the slot of a newly rooted block (the oldest slot every supermajority fork contains).

RootSubscribe does not accept options.

func (*Client) SignatureSubscribe 

func (c *Client) SignatureSubscribe(ctx context.Context, sig solana.Signature, cfg ...rpc.SignatureSubscribeCfg) (*SignatureSubscription, error)

SignatureSubscribe subscribes to the status of a single transaction signature. The server delivers exactly one notification once the signature is confirmed (or fails), then unsubscribes automatically.

func (*Client) SlotSubscribe 

func (c *Client) SlotSubscribe(ctx context.Context) (*SlotSubscription, error)

SlotSubscribe subscribes to slot updates. Each notification reports the current parent, root, and the newly processed slot.

SlotSubscribe does not accept options.

func (*Client) SlotsUpdatesSubscribe 

func (c *Client) SlotsUpdatesSubscribe(ctx context.Context) (*SlotsUpdatesSubscription, error)

SlotsUpdatesSubscribe subscribes to detailed slot lifecycle events. Unlike SlotSubscribe, this fires multiple times per slot, one event per lifecycle stage (shred received, bank created, frozen, rooted, ...).

SlotsUpdatesSubscribe is an unstable RPC method; require explicit server-side opt-in via --rpc-pubsub-enable-slots-updates-subscription.

SlotsUpdatesSubscribe does not accept options.

func (*Client) Subscribe 

func (c *Client) Subscribe(
	ctx context.Context,
	method, unsubMethod string,
	params []any,
	dispatch func([]byte),
	shutdown func(),
) (*Subscription, error)

Subscribe sends a subscribe request and blocks until the server acknowledges. By the time Subscribe returns, the subscription is already registered in the subscriptions map (by handleReply), so any notifications that arrive immediately after the reply are routed correctly.

method and unsubMethod are the JSON-RPC method names (e.g. "accountSubscribe" and "accountUnsubscribe"). params is the request's params array. dispatch is invoked for every incoming notification payload. shutdown is invoked once when the subscription ends (via Unsubscribe or client Close).

type LogNotification 

type LogNotification struct {
	// Slot is the slot at which the transaction was processed.
	Slot uint64 `json:"-"`
	// Signature is the base58-encoded transaction signature.
	Signature string `json:"signature"`
	// Err is the transaction error, or nil on success.
	Err any `json:"err"`
	// Logs is the program log messages emitted by the transaction.
	Logs []string `json:"logs"`
}

LogNotification is a single update delivered to a LogsSubscription. Slot comes from the JSON-RPC context envelope; the rest decode directly from the value object.

type LogsFilter 

type LogsFilter struct {
	// All subscribes to every transaction except vote transactions.
	All bool
	// AllWithVotes subscribes to every transaction including votes.
	AllWithVotes bool
	// Mentions restricts the subscription to transactions that
	// mention at least one of these addresses. Solana currently
	// limits this to a single pubkey per subscription.
	Mentions []solana.PublicKey
}

LogsFilter is the filter passed to LogsSubscribe. Exactly one of All, AllWithVotes, or Mentions should be set; if none are set, the filter defaults to All.

type LogsSubscription 

type LogsSubscription struct {
	*Subscription
	// contains filtered or unexported fields
}

LogsSubscription is the handle returned by LogsSubscribe.

func (*LogsSubscription) Recv 

func (s *LogsSubscription) Recv() <-chan *LogNotification

Recv returns the channel that delivers log notifications.

type ProgramNotification 

type ProgramNotification struct {
	Slot    uint64              `json:"-"`
	Pubkey  solana.PublicKey    `json:"pubkey"`
	Account *solana.AccountInfo `json:"account"`
}

ProgramNotification is a single update delivered to a ProgramSubscription. Pubkey is the account that changed and Account is its new state. Slot is set from the JSON-RPC context envelope after decode; the value-object fields decode directly via json: tags.

type ProgramSubscription 

type ProgramSubscription struct {
	*Subscription
	// contains filtered or unexported fields
}

ProgramSubscription is the handle returned by ProgramSubscribe.

func (*ProgramSubscription) Recv 

func (s *ProgramSubscription) Recv() <-chan *ProgramNotification

Recv returns the channel that delivers program-owned account updates.

type RootSubscription 

type RootSubscription struct {
	*Subscription
	// contains filtered or unexported fields
}

RootSubscription is the handle returned by RootSubscribe.

func (*RootSubscription) Recv 

func (s *RootSubscription) Recv() <-chan uint64

Recv returns the channel that delivers root slot updates.

type SignatureNotification 

type SignatureNotification struct {
	Slot uint64 `json:"-"`
	Err  any    `json:"err"` // nil on success
}

SignatureNotification is the one-shot update delivered to a SignatureSubscription once the target signature has reached the requested commitment level. Slot is set from the JSON-RPC context envelope after decode.

type SignatureSubscription 

type SignatureSubscription struct {
	*Subscription
	// contains filtered or unexported fields
}

SignatureSubscription is the handle returned by SignatureSubscribe.

func (*SignatureSubscription) Recv 

func (s *SignatureSubscription) Recv() <-chan *SignatureNotification

Recv returns the channel that delivers the single expected signature notification. After the notification arrives the subscription is done; the server automatically unsubscribes.

type SlotInfo 

type SlotInfo struct {
	Parent uint64 `json:"parent"`
	Root   uint64 `json:"root"`
	Slot   uint64 `json:"slot"`
}

SlotInfo is a single update delivered to a SlotSubscription.

type SlotSubscription 

type SlotSubscription struct {
	*Subscription
	// contains filtered or unexported fields
}

SlotSubscription is the handle returned by SlotSubscribe.

func (*SlotSubscription) Recv 

func (s *SlotSubscription) Recv() <-chan *SlotInfo

Recv returns the channel that delivers slot updates.

type SlotUpdate 

type SlotUpdate struct {
	Type      string `json:"type"`
	Slot      uint64 `json:"slot"`
	Parent    uint64 `json:"parent,omitempty"`
	Timestamp int64  `json:"timestamp"`
	Err       string `json:"err,omitempty"`
}

SlotUpdate is a single event delivered to a SlotsUpdatesSubscription. Type names the kind of event ("firstShredReceived", "completed", "createdBank", "frozen", "dead", "optimisticConfirmation", "root").

type SlotsUpdatesSubscription 

type SlotsUpdatesSubscription struct {
	*Subscription
	// contains filtered or unexported fields
}

SlotsUpdatesSubscription is the handle returned by SlotsUpdatesSubscribe.

func (*SlotsUpdatesSubscription) Recv 

func (s *SlotsUpdatesSubscription) Recv() <-chan *SlotUpdate

Recv returns the channel that delivers slot update events.

type Subscription 

type Subscription struct {
	// contains filtered or unexported fields
}

Subscription is the handle returned by Subscribe. It exposes the server-assigned id, a Done channel that fires when the subscription ends, and an Unsubscribe method. Typed subscriptions in the client package embed *Subscription to inherit these.

func (*Subscription) Done 

func (s *Subscription) Done() <-chan struct{}

Done returns a channel that is closed when the subscription ends, either because Unsubscribe was called or because the underlying client was closed.

func (*Subscription) ID 

func (s *Subscription) ID() uint64

ID returns the server-assigned subscription id.

func (*Subscription) Unsubscribe 

func (s *Subscription) Unsubscribe(ctx context.Context) error

Unsubscribe cancels the subscription and releases server-side resources. It is safe to call Unsubscribe multiple times; subsequent calls are no-ops.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.