cosmos

package
v1.0.13 Latest Latest
Warning

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

 Go to latest Published: Jan 22, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package cosmos provides a DataExtractor implementation for Cosmos SDK-based blockchains.

The CosmosDataExtractor knows how to extract quality data from multiple response formats:

  • CometBFT JSON-RPC responses (status endpoint)
  • Cosmos SDK REST responses (status endpoint)

Cosmos chains can return data in different formats depending on the endpoint:

  • /status (CometBFT): JSON-RPC with node_info, sync_info
  • /cosmos/base/node/v1beta1/status: REST with height field

Index

Constants

View Source 
const QoSType = "cosmossdk"

QoSType is the QoS type for the CosmosSDK blockchain.

Variables

This section is empty.

Functions

This section is empty.

Types

type CosmosDataExtractor added in v1.0.10 

type CosmosDataExtractor struct{}

CosmosDataExtractor extracts quality data from Cosmos SDK and CometBFT responses. It handles multiple response formats common in the Cosmos ecosystem.

func NewCosmosDataExtractor added in v1.0.10 

func NewCosmosDataExtractor() *CosmosDataExtractor

NewCosmosDataExtractor creates a new Cosmos data extractor.

func (*CosmosDataExtractor) ExtractBlockHeight added in v1.0.10 

func (e *CosmosDataExtractor) ExtractBlockHeight(response []byte) (int64, error)

ExtractBlockHeight extracts the block height from a Cosmos response. Supports both CometBFT status (JSON-RPC) and Cosmos SDK REST status responses.

CometBFT format: 

{"jsonrpc":"2.0","id":1,"result":{"sync_info":{"latest_block_height":"12345"}}}

Cosmos SDK REST format: 

{"height":"12345"}

Returns:

  • Block height as int64
  • Error if extraction fails or response doesn't contain block height

func (*CosmosDataExtractor) ExtractChainID added in v1.0.10 

func (e *CosmosDataExtractor) ExtractChainID(response []byte) (string, error)

ExtractChainID extracts the chain identifier from a Cosmos response. The chain ID comes from the CometBFT status response's node_info.network field.

Expected response format (CometBFT): 

{"jsonrpc":"2.0","id":1,"result":{"node_info":{"network":"cosmoshub-4"}}}

Returns:

  • Chain ID as string (e.g., "cosmoshub-4", "osmosis-1")
  • Error if extraction fails or response doesn't contain chain ID

func (*CosmosDataExtractor) IsArchival added in v1.0.10 

func (e *CosmosDataExtractor) IsArchival(response []byte) (bool, error)

IsArchival determines if the endpoint supports archival queries. For Cosmos chains, this is typically checked by querying historical block data.

An archival node will return data for historical queries. A non-archival (pruned) node will return an error for old blocks.

Returns:

  • true if endpoint is archival (query succeeded)
  • false if endpoint is not archival (query failed with pruning error)
  • Error if archival status cannot be determined

func (*CosmosDataExtractor) IsSyncing added in v1.0.10 

func (e *CosmosDataExtractor) IsSyncing(response []byte) (bool, error)

IsSyncing determines if the endpoint is currently syncing. Uses the CometBFT status response's sync_info.catching_up field.

Expected response format: 

{"jsonrpc":"2.0","id":1,"result":{"sync_info":{"catching_up":false}}}

Returns:

  • true if endpoint is syncing (catching_up = true)
  • false if endpoint is synced (catching_up = false)
  • Error if sync status cannot be determined

func (*CosmosDataExtractor) IsValidResponse added in v1.0.10 

func (e *CosmosDataExtractor) IsValidResponse(response []byte) (bool, error)

IsValidResponse checks if the response is valid. Supports both JSON-RPC and REST response formats.

Returns:

  • true if response is valid (correct format, no errors)
  • false if response is invalid (malformed, contains error)
  • Error if validation fails unexpectedly

type CosmosSDKServiceQoSConfig 

type CosmosSDKServiceQoSConfig interface {
	ServiceQoSConfig // Using locally defined interface to avoid circular dependency
	// contains filtered or unexported methods
}

CosmosSDKServiceQoSConfig is the configuration for the CosmosSDK service QoS.

func NewCosmosSDKServiceQoSConfig 

func NewCosmosSDKServiceQoSConfig(
	serviceID protocol.ServiceID,
	cosmosSDKChainID string,
	evmChainID string,
	supportedAPIs map[sharedtypes.RPCType]struct{},
) CosmosSDKServiceQoSConfig

NewCosmosSDKServiceQoSConfig creates a new CosmosSDK service configuration.

func NewCosmosSDKServiceQoSConfigWithSyncAllowance added in v1.0.10 

func NewCosmosSDKServiceQoSConfigWithSyncAllowance(
	serviceID protocol.ServiceID,
	cosmosSDKChainID string,
	evmChainID string,
	supportedAPIs map[sharedtypes.RPCType]struct{},
	syncAllowance uint64,
) CosmosSDKServiceQoSConfig

NewCosmosSDKServiceQoSConfigWithSyncAllowance creates a new CosmosSDK service configuration with custom sync allowance.

type DefaultNodeInfo 

type DefaultNodeInfo struct {
	Network string `json:"network"` // network/chain ID
}

DefaultNodeInfo is the basic node information exchanged between two peers during the CometBFT P2P handshake.

type QoS 

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

QoS implements ServiceQoS for CosmosSDK-based chains. It handles chain-specific:

  • Request parsing (both REST and JSON-RPC)
  • Response building
  • Endpoint validation and selection

func NewSimpleQoSInstance added in v1.0.10 

func NewSimpleQoSInstance(logger polylog.Logger, serviceID protocol.ServiceID) *QoS

NewSimpleQoSInstance creates a minimal CosmosSDK QoS instance without chain-specific validation. Validation (chain ID, etc.) is now handled by active health checks. This constructor only requires the service ID and provides REST/JSON-RPC request parsing.

func NewSimpleQoSInstanceWithAPIs added in v1.0.10 

func NewSimpleQoSInstanceWithAPIs(logger polylog.Logger, serviceID protocol.ServiceID, syncAllowance uint64, supportedAPIs map[sharedtypes.RPCType]struct{}) *QoS

NewSimpleQoSInstanceWithAPIs creates a minimal CosmosSDK QoS instance with custom supported APIs. This is useful for hybrid chains (e.g., XRPLEVM) that support both CosmosSDK and EVM APIs. Validation (chain ID, etc.) is now handled by active health checks. If syncAllowance is 0, the default value is used.

func NewSimpleQoSInstanceWithSyncAllowance added in v1.0.10 

func NewSimpleQoSInstanceWithSyncAllowance(logger polylog.Logger, serviceID protocol.ServiceID, syncAllowance uint64) *QoS

NewSimpleQoSInstanceWithSyncAllowance creates a minimal CosmosSDK QoS instance with custom sync allowance. Validation (chain ID, etc.) is now handled by active health checks. If syncAllowance is 0, the default value is used.

func (QoS) ApplyObservations 

func (ss QoS) ApplyObservations(observations *qosobservations.Observations) error

ApplyObservations updates endpoint storage and blockchain state from observations.

func (QoS) CheckWebsocketConnection 

func (rv QoS) CheckWebsocketConnection() bool

CheckWebsocketConnection returns true if the endpoint supports Websocket connections.

func (*QoS) GetPerceivedBlockNumber added in v1.0.12 

func (qos *QoS) GetPerceivedBlockNumber() uint64

GetPerceivedBlockNumber returns the perceived current block number. Used by health checks for block height validation. Returns 0 if no block number has been observed yet.

Implements gateway.QoSService interface.

func (QoS) GetRequiredQualityChecks 

func (rv QoS) GetRequiredQualityChecks(endpointAddr protocol.EndpointAddr) []gateway.RequestQoSContext

GetRequiredQualityChecks returns the list of quality checks required for an endpoint. It is called in the `gateway/hydrator.go` file on each run of the hydrator.

func (*QoS) HydrateDisqualifiedEndpointsResponse 

func (qos *QoS) HydrateDisqualifiedEndpointsResponse(serviceID protocol.ServiceID, details *devtools.DisqualifiedEndpointResponse)

HydrateDisqualifiedEndpointsResponse hydrates the disqualified endpoint response with the QoS-specific data.

  • takes a pointer to the DisqualifiedEndpointResponse
  • called by the devtools.DisqualifiedEndpointReporter to fill it with the QoS-specific data.

func (*QoS) ParseHTTPRequest 

func (qos *QoS) ParseHTTPRequest(_ context.Context, req *http.Request, detectedRPCType sharedtypes.RPCType) (gateway.RequestQoSContext, bool)

ParseHTTPRequest builds a request context from an HTTP request. Returns (requestContext, true) if the request is valid Returns (errorContext, false) if the request is not valid.

Supports both REST endpoints (/health, /status) and JSON-RPC requests.

Implements gateway.QoSService interface.

func (*QoS) ParseWebsocketRequest 

func (qos *QoS) ParseWebsocketRequest(_ context.Context) (gateway.RequestQoSContext, bool)

ParseWebsocketRequest builds a request context from the provided Websocket request. Websocket connection requests do not have a body, so we don't need to parse it.

Implements gateway.QoSService interface.

func (QoS) Select 

func (ss QoS) Select(availableEndpoints protocol.EndpointAddrList) (protocol.EndpointAddr, error)

Select returns an endpoint address matching an entry from the list of available endpoints. available endpoints are filtered based on their validity first. A random endpoint is then returned from the filtered list of valid endpoints.

func (QoS) SelectMultiple 

func (ss QoS) SelectMultiple(allAvailableEndpoints protocol.EndpointAddrList, numEndpoints uint) (protocol.EndpointAddrList, error)

SelectMultiple returns multiple endpoint addresses from the list of valid endpoints. Valid endpoints are determined by filtering the available endpoints based on their validity criteria. If numEndpoints is 0, it defaults to 1.

func (*QoS) UpdateFromExtractedData added in v1.0.10 

func (qos *QoS) UpdateFromExtractedData(endpointAddr protocol.EndpointAddr, data *qostypes.ExtractedData) error

UpdateFromExtractedData updates QoS state from extracted observation data. Called by the observation pipeline after async parsing completes. This updates the perceived block number and stores the endpoint's block number observation.

Implements gateway.QoSService interface.

type ResultStatus 

type ResultStatus struct {
	NodeInfo DefaultNodeInfo `json:"node_info"`
	SyncInfo SyncInfo        `json:"sync_info"`
}

Node Status

type ServiceQoSConfig 

type ServiceQoSConfig interface {
	GetServiceID() protocol.ServiceID
	GetServiceQoSType() string
}

ServiceQoSConfig defines the base interface for service QoS configurations. This avoids circular dependency with the config package.

type SyncInfo 

type SyncInfo struct {
	LatestBlockHeight string `json:"latest_block_height"`
	CatchingUp        bool   `json:"catching_up"`
}

Info about the node's syncing state

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.