hybrid_client

package
v5.4.3 Latest Latest
Warning

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

Go to latest
Published: Sep 8, 2025 License: Apache-2.0 Imports: 20 Imported by: 0

README

Hybrid Client

This package provides a hybrid client implementation that maintains compatibility between Cosmos SDK v47 and v50 event handling.

Background

In Cosmos SDK v50, there were significant changes to block event handling:

  • BeginBlockEvents and EndBlockEvents were deprecated
  • A new event type FinalizeBlockEvents was introduced to replace them

This hybrid client seamlessly handles both versions by:

  • Supporting the legacy BeginBlockEvents and EndBlockEvents for v47 compatibility
  • Supporting the new FinalizeBlockEvents for v50 compatibility
  • Aggregating all events into FinalizeBlockEvents for consistent downstream handling

This allows applications to work with both v47 and v50 chains without needing version-specific event handling logic.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BatchHTTP

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

BatchHTTP provides the same interface as `HTTP`, but allows for batching of requests (as per https://www.jsonrpc.org/specification#batch). Do not instantiate directly - rather use the HTTP.NewBatch() method to create an instance of this struct.

Batching of HTTP requests is thread-safe in the sense that multiple goroutines can each create their own batches and send them using the same HTTP client. Multiple goroutines could also enqueue transactions in a single batch, but ordering of transactions in the batch cannot be guaranteed in such an example.

func (BatchHTTP) ABCIInfo

func (c BatchHTTP) ABCIInfo(ctx context.Context) (*ctypes.ResultABCIInfo, error)

func (BatchHTTP) ABCIQuery

func (c BatchHTTP) ABCIQuery(
	ctx context.Context,
	path string,
	data bytes.HexBytes,
) (*ctypes.ResultABCIQuery, error)

func (BatchHTTP) ABCIQueryWithOptions

func (c BatchHTTP) ABCIQueryWithOptions(
	ctx context.Context,
	path string,
	data bytes.HexBytes,
	opts rpcclient.ABCIQueryOptions,
) (*ctypes.ResultABCIQuery, error)

func (BatchHTTP) Block

func (c BatchHTTP) Block(ctx context.Context, height *int64) (*ctypes.ResultBlock, error)

func (BatchHTTP) BlockByHash

func (c BatchHTTP) BlockByHash(ctx context.Context, hash []byte) (*ctypes.ResultBlock, error)

func (BatchHTTP) BlockResults

func (c BatchHTTP) BlockResults(
	ctx context.Context,
	height *int64,
) (*ResultBlockResults, error)

func (BatchHTTP) BlockSearch

func (c BatchHTTP) BlockSearch(
	ctx context.Context,
	query string,
	page, perPage *int,
	orderBy string,
) (*ctypes.ResultBlockSearch, error)

func (BatchHTTP) BlockchainInfo

func (c BatchHTTP) BlockchainInfo(
	ctx context.Context,
	minHeight,
	maxHeight int64,
) (*ctypes.ResultBlockchainInfo, error)

func (BatchHTTP) BroadcastEvidence

func (c BatchHTTP) BroadcastEvidence(
	ctx context.Context,
	ev types.Evidence,
) (*ctypes.ResultBroadcastEvidence, error)

func (BatchHTTP) BroadcastTxAsync

func (c BatchHTTP) BroadcastTxAsync(
	ctx context.Context,
	tx types.Tx,
) (*ctypes.ResultBroadcastTx, error)

func (BatchHTTP) BroadcastTxCommit

func (c BatchHTTP) BroadcastTxCommit(
	ctx context.Context,
	tx types.Tx,
) (*ctypes.ResultBroadcastTxCommit, error)

func (BatchHTTP) BroadcastTxSync

func (c BatchHTTP) BroadcastTxSync(
	ctx context.Context,
	tx types.Tx,
) (*ctypes.ResultBroadcastTx, error)

func (BatchHTTP) CheckTx

func (c BatchHTTP) CheckTx(ctx context.Context, tx types.Tx) (*ctypes.ResultCheckTx, error)

func (*BatchHTTP) Clear

func (b *BatchHTTP) Clear() int

Clear will empty out this batch of requests and return the number of requests that were cleared out.

func (BatchHTTP) Commit

func (c BatchHTTP) Commit(ctx context.Context, height *int64) (*ctypes.ResultCommit, error)

func (BatchHTTP) ConsensusParams

func (c BatchHTTP) ConsensusParams(
	ctx context.Context,
	height *int64,
) (*ctypes.ResultConsensusParams, error)

func (BatchHTTP) ConsensusState

func (c BatchHTTP) ConsensusState(ctx context.Context) (*ctypes.ResultConsensusState, error)

func (*BatchHTTP) Count

func (b *BatchHTTP) Count() int

Count returns the number of enqueued requests waiting to be sent.

func (BatchHTTP) DumpConsensusState

func (c BatchHTTP) DumpConsensusState(ctx context.Context) (*ctypes.ResultDumpConsensusState, error)

func (BatchHTTP) Genesis

func (c BatchHTTP) Genesis(ctx context.Context) (*ctypes.ResultGenesis, error)

func (BatchHTTP) GenesisChunked

func (c BatchHTTP) GenesisChunked(ctx context.Context, id uint) (*ctypes.ResultGenesisChunk, error)

func (BatchHTTP) Header

func (c BatchHTTP) Header(ctx context.Context, height *int64) (*ctypes.ResultHeader, error)

func (BatchHTTP) HeaderByHash

func (c BatchHTTP) HeaderByHash(ctx context.Context, hash bytes.HexBytes) (*ctypes.ResultHeader, error)

func (BatchHTTP) Health

func (c BatchHTTP) Health(ctx context.Context) (*ctypes.ResultHealth, error)

func (BatchHTTP) NetInfo

func (c BatchHTTP) NetInfo(ctx context.Context) (*ctypes.ResultNetInfo, error)

func (BatchHTTP) NumUnconfirmedTxs

func (c BatchHTTP) NumUnconfirmedTxs(ctx context.Context) (*ctypes.ResultUnconfirmedTxs, error)

func (*BatchHTTP) Send

func (b *BatchHTTP) Send(ctx context.Context) ([]interface{}, error)

Send is a convenience function for an HTTP batch that will trigger the compilation of the batched requests and send them off using the client as a single request. On success, this returns a list of the deserialized results from each request in the sent batch.

func (BatchHTTP) Status

func (c BatchHTTP) Status(ctx context.Context) (*ctypes.ResultStatus, error)

func (BatchHTTP) Tx

func (c BatchHTTP) Tx(ctx context.Context, hash []byte, prove bool) (*ctypes.ResultTx, error)

func (BatchHTTP) TxSearch

func (c BatchHTTP) TxSearch(
	ctx context.Context,
	query string,
	prove bool,
	page,
	perPage *int,
	orderBy string,
) (*ctypes.ResultTxSearch, error)

func (BatchHTTP) UnconfirmedTxs

func (c BatchHTTP) UnconfirmedTxs(
	ctx context.Context,
	limit *int,
) (*ctypes.ResultUnconfirmedTxs, error)

func (BatchHTTP) Validators

func (c BatchHTTP) Validators(
	ctx context.Context,
	height *int64,
	page,
	perPage *int,
) (*ctypes.ResultValidators, error)

type HTTP

type HTTP struct {
	*WSEvents
	// contains filtered or unexported fields
}

HTTP is a Client implementation that communicates with a CometBFT node over JSON RPC and WebSockets.

This is the main implementation you probably want to use in production code. There are other implementations when calling the CometBFT node in-process (Local), or when you want to mock out the server for test code (mock).

You can subscribe for any event published by CometBFT using Subscribe method. Note delivery is best-effort. If you don't read events fast enough or network is slow, CometBFT might cancel the subscription. The client will attempt to resubscribe (you don't need to do anything). It will keep trying every second indefinitely until successful.

Request batching is available for JSON RPC requests over HTTP, which conforms to the JSON RPC specification (https://www.jsonrpc.org/specification#batch). See the example for more details.

Example:

c, err := New("http://192.168.1.10:26657", "/websocket")
if err != nil {
	// handle error
}

// call Start/Stop if you're subscribing to events
err = c.Start()
if err != nil {
	// handle error
}
defer c.Stop()

res, err := c.Status()
if err != nil {
	// handle error
}

// handle result

func New

func New(remote, wsEndpoint string) (*HTTP, error)

New takes a remote endpoint in the form <protocol>://<host>:<port> and the websocket path (which always seems to be "/websocket") An error is returned on invalid remote. The function panics when remote is nil.

func NewWithClient

func NewWithClient(remote, wsEndpoint string, client *http.Client) (*HTTP, error)

NewWithClient allows for setting a custom http client (See New). An error is returned on invalid remote. The function panics when remote is nil.

func NewWithTimeout

func NewWithTimeout(remote, wsEndpoint string, timeout uint) (*HTTP, error)

Create timeout enabled http client

func (HTTP) ABCIInfo

func (c HTTP) ABCIInfo(ctx context.Context) (*ctypes.ResultABCIInfo, error)

func (HTTP) ABCIQuery

func (c HTTP) ABCIQuery(
	ctx context.Context,
	path string,
	data bytes.HexBytes,
) (*ctypes.ResultABCIQuery, error)

func (HTTP) ABCIQueryWithOptions

func (c HTTP) ABCIQueryWithOptions(
	ctx context.Context,
	path string,
	data bytes.HexBytes,
	opts rpcclient.ABCIQueryOptions,
) (*ctypes.ResultABCIQuery, error)

func (HTTP) Block

func (c HTTP) Block(ctx context.Context, height *int64) (*ctypes.ResultBlock, error)

func (HTTP) BlockByHash

func (c HTTP) BlockByHash(ctx context.Context, hash []byte) (*ctypes.ResultBlock, error)

func (HTTP) BlockResults

func (c HTTP) BlockResults(
	ctx context.Context,
	height *int64,
) (*ResultBlockResults, error)

func (HTTP) BlockSearch

func (c HTTP) BlockSearch(
	ctx context.Context,
	query string,
	page, perPage *int,
	orderBy string,
) (*ctypes.ResultBlockSearch, error)

func (HTTP) BlockchainInfo

func (c HTTP) BlockchainInfo(
	ctx context.Context,
	minHeight,
	maxHeight int64,
) (*ctypes.ResultBlockchainInfo, error)

func (HTTP) BroadcastEvidence

func (c HTTP) BroadcastEvidence(
	ctx context.Context,
	ev types.Evidence,
) (*ctypes.ResultBroadcastEvidence, error)

func (HTTP) BroadcastTxAsync

func (c HTTP) BroadcastTxAsync(
	ctx context.Context,
	tx types.Tx,
) (*ctypes.ResultBroadcastTx, error)

func (HTTP) BroadcastTxCommit

func (c HTTP) BroadcastTxCommit(
	ctx context.Context,
	tx types.Tx,
) (*ctypes.ResultBroadcastTxCommit, error)

func (HTTP) BroadcastTxSync

func (c HTTP) BroadcastTxSync(
	ctx context.Context,
	tx types.Tx,
) (*ctypes.ResultBroadcastTx, error)

func (HTTP) CheckTx

func (c HTTP) CheckTx(ctx context.Context, tx types.Tx) (*ctypes.ResultCheckTx, error)

func (HTTP) Commit

func (c HTTP) Commit(ctx context.Context, height *int64) (*ctypes.ResultCommit, error)

func (HTTP) ConsensusParams

func (c HTTP) ConsensusParams(
	ctx context.Context,
	height *int64,
) (*ctypes.ResultConsensusParams, error)

func (HTTP) ConsensusState

func (c HTTP) ConsensusState(ctx context.Context) (*ctypes.ResultConsensusState, error)

func (HTTP) DumpConsensusState

func (c HTTP) DumpConsensusState(ctx context.Context) (*ctypes.ResultDumpConsensusState, error)

func (HTTP) Genesis

func (c HTTP) Genesis(ctx context.Context) (*ctypes.ResultGenesis, error)

func (HTTP) GenesisChunked

func (c HTTP) GenesisChunked(ctx context.Context, id uint) (*ctypes.ResultGenesisChunk, error)

func (HTTP) Header

func (c HTTP) Header(ctx context.Context, height *int64) (*ctypes.ResultHeader, error)

func (HTTP) HeaderByHash

func (c HTTP) HeaderByHash(ctx context.Context, hash bytes.HexBytes) (*ctypes.ResultHeader, error)

func (HTTP) Health

func (c HTTP) Health(ctx context.Context) (*ctypes.ResultHealth, error)

func (HTTP) NetInfo

func (c HTTP) NetInfo(ctx context.Context) (*ctypes.ResultNetInfo, error)

func (*HTTP) NewBatch

func (c *HTTP) NewBatch() *BatchHTTP

NewBatch creates a new batch client for this HTTP client.

func (HTTP) NumUnconfirmedTxs

func (c HTTP) NumUnconfirmedTxs(ctx context.Context) (*ctypes.ResultUnconfirmedTxs, error)

func (*HTTP) Remote

func (c *HTTP) Remote() string

Remote returns the remote network address in a string form.

func (*HTTP) SetLogger

func (c *HTTP) SetLogger(l log.Logger)

SetLogger sets a logger.

func (HTTP) Status

func (c HTTP) Status(ctx context.Context) (*ctypes.ResultStatus, error)

func (HTTP) Tx

func (c HTTP) Tx(ctx context.Context, hash []byte, prove bool) (*ctypes.ResultTx, error)

func (HTTP) TxSearch

func (c HTTP) TxSearch(
	ctx context.Context,
	query string,
	prove bool,
	page,
	perPage *int,
	orderBy string,
) (*ctypes.ResultTxSearch, error)

func (HTTP) UnconfirmedTxs

func (c HTTP) UnconfirmedTxs(
	ctx context.Context,
	limit *int,
) (*ctypes.ResultUnconfirmedTxs, error)

func (HTTP) Validators

func (c HTTP) Validators(
	ctx context.Context,
	height *int64,
	page,
	perPage *int,
) (*ctypes.ResultValidators, error)

type Peer

type Peer struct {
	NodeInfo         p2p.DefaultNodeInfo  `json:"node_info"`
	IsOutbound       bool                 `json:"is_outbound"`
	ConnectionStatus p2p.ConnectionStatus `json:"connection_status"`
	RemoteIP         string               `json:"remote_ip"`
}

A peer

type PeerStateInfo

type PeerStateInfo struct {
	NodeAddress string          `json:"node_address"`
	PeerState   json.RawMessage `json:"peer_state"`
}

UNSTABLE

type ResultABCIInfo

type ResultABCIInfo struct {
	Response abci.ResponseInfo `json:"response"`
}

Info abci msg

type ResultABCIQuery

type ResultABCIQuery struct {
	Response abci.ResponseQuery `json:"response"`
}

Query abci msg

type ResultBlock

type ResultBlock struct {
	BlockID types.BlockID `json:"block_id"`
	Block   *types.Block  `json:"block"`
}

Single block (with meta)

type ResultBlockResults

type ResultBlockResults struct {
	Height                int64                     `json:"height"`
	TxsResults            []*abci.ResponseDeliverTx `json:"txs_results"`
	FinalizeBlockEvents   []abci.Event              `json:"finalize_block_events"`
	EndBlockEvents        []abci.Event              `json:"end_block_events"`
	BeginBlockEvents      []abci.Event              `json:"begin_block_events"`
	ValidatorUpdates      []abci.ValidatorUpdate    `json:"validator_updates"`
	ConsensusParamUpdates *cmtproto.ConsensusParams `json:"consensus_param_updates"`
	AppHash               []byte                    `json:"app_hash"`
}

ABCI results from a block

type ResultBlockSearch

type ResultBlockSearch struct {
	Blocks     []*ResultBlock `json:"blocks"`
	TotalCount int            `json:"total_count"`
}

ResultBlockSearch defines the RPC response type for a block search by events.

type ResultBlockchainInfo

type ResultBlockchainInfo struct {
	LastHeight int64              `json:"last_height"`
	BlockMetas []*types.BlockMeta `json:"block_metas"`
}

List of blocks

type ResultBroadcastEvidence

type ResultBroadcastEvidence struct {
	Hash []byte `json:"hash"`
}

Result of broadcasting evidence

type ResultBroadcastTx

type ResultBroadcastTx struct {
	Code      uint32         `json:"code"`
	Data      bytes.HexBytes `json:"data"`
	Log       string         `json:"log"`
	Codespace string         `json:"codespace"`

	Hash bytes.HexBytes `json:"hash"`
}

CheckTx result

type ResultBroadcastTxCommit

type ResultBroadcastTxCommit struct {
	CheckTx  abci.ResponseCheckTx   `json:"check_tx"`
	TxResult abci.ResponseDeliverTx `json:"tx_result"`
	Hash     bytes.HexBytes         `json:"hash"`
	Height   int64                  `json:"height"`
}

CheckTx and ExecTx results

type ResultCheckTx

type ResultCheckTx struct {
	abci.ResponseCheckTx
}

ResultCheckTx wraps abci.ResponseCheckTx.

type ResultCommit

type ResultCommit struct {
	types.SignedHeader `json:"signed_header"`
	CanonicalCommit    bool `json:"canonical"`
}

Commit and Header

func NewResultCommit

func NewResultCommit(header *types.Header, commit *types.Commit, canonical bool) *ResultCommit

NewResultCommit is a helper to initialize the ResultCommit with the embedded struct

type ResultConsensusParams

type ResultConsensusParams struct {
	BlockHeight     int64                 `json:"block_height"`
	ConsensusParams types.ConsensusParams `json:"consensus_params"`
}

ConsensusParams for given height

type ResultConsensusState

type ResultConsensusState struct {
	RoundState json.RawMessage `json:"round_state"`
}

UNSTABLE

type ResultDialPeers

type ResultDialPeers struct {
	Log string `json:"log"`
}

Log from dialing peers

type ResultDialSeeds

type ResultDialSeeds struct {
	Log string `json:"log"`
}

Log from dialing seeds

type ResultDumpConsensusState

type ResultDumpConsensusState struct {
	RoundState json.RawMessage `json:"round_state"`
	Peers      []PeerStateInfo `json:"peers"`
}

Info about the consensus state. UNSTABLE

type ResultEvent

type ResultEvent struct {
	Query  string              `json:"query"`
	Data   types.TMEventData   `json:"data"`
	Events map[string][]string `json:"events"`
}

Event data from a subscription

type ResultGenesis

type ResultGenesis struct {
	Genesis *types.GenesisDoc `json:"genesis"`
}

Genesis file

type ResultGenesisChunk

type ResultGenesisChunk struct {
	ChunkNumber int    `json:"chunk"`
	TotalChunks int    `json:"total"`
	Data        string `json:"data"`
}

ResultGenesisChunk is the output format for the chunked/paginated interface. These chunks are produced by converting the genesis document to JSON and then splitting the resulting payload into 16 megabyte blocks and then base64 encoding each block.

type ResultHeader

type ResultHeader struct {
	Header *types.Header `json:"header"`
}

ResultHeader represents the response for a Header RPC Client query

type ResultHealth

type ResultHealth struct{}

empty results

type ResultNetInfo

type ResultNetInfo struct {
	Listening bool     `json:"listening"`
	Listeners []string `json:"listeners"`
	NPeers    int      `json:"n_peers"`
	Peers     []Peer   `json:"peers"`
}

Info about peer connections

type ResultStatus

type ResultStatus struct {
	NodeInfo      p2p.DefaultNodeInfo `json:"node_info"`
	SyncInfo      SyncInfo            `json:"sync_info"`
	ValidatorInfo ValidatorInfo       `json:"validator_info"`
}

Node Status

func (*ResultStatus) TxIndexEnabled

func (s *ResultStatus) TxIndexEnabled() bool

Is TxIndexing enabled

type ResultSubscribe

type ResultSubscribe struct{}

empty results

type ResultTx

type ResultTx struct {
	Hash     bytes.HexBytes         `json:"hash"`
	Height   int64                  `json:"height"`
	Index    uint32                 `json:"index"`
	TxResult abci.ResponseDeliverTx `json:"tx_result"`
	Tx       types.Tx               `json:"tx"`
	Proof    types.TxProof          `json:"proof,omitempty"`
}

Result of querying for a tx

type ResultTxSearch

type ResultTxSearch struct {
	Txs        []*ResultTx `json:"txs"`
	TotalCount int         `json:"total_count"`
}

Result of searching for txs

type ResultUnconfirmedTxs

type ResultUnconfirmedTxs struct {
	Count      int        `json:"n_txs"`
	Total      int        `json:"total"`
	TotalBytes int64      `json:"total_bytes"`
	Txs        []types.Tx `json:"txs"`
}

List of mempool txs

type ResultUnsafeFlushMempool

type ResultUnsafeFlushMempool struct{}

empty results

type ResultUnsafeProfile

type ResultUnsafeProfile struct{}

empty results

type ResultUnsubscribe

type ResultUnsubscribe struct{}

empty results

type ResultValidators

type ResultValidators struct {
	BlockHeight int64              `json:"block_height"`
	Validators  []*types.Validator `json:"validators"`
	// Count of actual validators in this result
	Count int `json:"count"`
	// Total number of validators
	Total int `json:"total"`
}

Validators for a height.

type SyncInfo

type SyncInfo struct {
	LatestBlockHash   bytes.HexBytes `json:"latest_block_hash"`
	LatestAppHash     bytes.HexBytes `json:"latest_app_hash"`
	LatestBlockHeight int64          `json:"latest_block_height"`
	LatestBlockTime   time.Time      `json:"latest_block_time"`

	EarliestBlockHash   bytes.HexBytes `json:"earliest_block_hash"`
	EarliestAppHash     bytes.HexBytes `json:"earliest_app_hash"`
	EarliestBlockHeight int64          `json:"earliest_block_height"`
	EarliestBlockTime   time.Time      `json:"earliest_block_time"`

	CatchingUp bool `json:"catching_up"`
}

Info about the node's syncing state

type ValidatorInfo

type ValidatorInfo struct {
	Address     bytes.HexBytes `json:"address"`
	PubKey      crypto.PubKey  `json:"pub_key"`
	VotingPower int64          `json:"voting_power"`
}

Info about the node's validator

type WSEvents

type WSEvents struct {
	service.BaseService
	// contains filtered or unexported fields
}

WSEvents is a wrapper around WSClient, which implements EventsClient.

func (*WSEvents) OnStart

func (w *WSEvents) OnStart() error

OnStart implements service.Service by starting WSClient and event loop.

func (*WSEvents) OnStop

func (w *WSEvents) OnStop()

OnStop implements service.Service by stopping WSClient.

func (*WSEvents) Subscribe

func (w *WSEvents) Subscribe(ctx context.Context, _, query string,
	outCapacity ...int,
) (out <-chan ctypes.ResultEvent, err error)

Subscribe implements EventsClient by using WSClient to subscribe given subscriber to query. By default, returns a channel with cap=1. Error is returned if it fails to subscribe.

Channel is never closed to prevent clients from seeing an erroneous event.

It returns an error if WSEvents is not running.

func (*WSEvents) Unsubscribe

func (w *WSEvents) Unsubscribe(ctx context.Context, _, query string) error

Unsubscribe implements EventsClient by using WSClient to unsubscribe given subscriber from query.

It returns an error if WSEvents is not running.

func (*WSEvents) UnsubscribeAll

func (w *WSEvents) UnsubscribeAll(ctx context.Context, _ string) error

UnsubscribeAll implements EventsClient by using WSClient to unsubscribe given subscriber from all the queries.

It returns an error if WSEvents is not running.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL