evm

package
v1.0.11 Latest Latest
Warning

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

 Go to latest Published: Jan 21, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package evm provides a DataExtractor implementation for EVM-based blockchains.

The EVMDataExtractor knows how to extract quality data from EVM JSON-RPC responses:

  • Block height from eth_blockNumber responses
  • Chain ID from eth_chainId responses
  • Sync status from eth_syncing responses
  • Archival status from historical query responses (e.g., eth_getBalance)
  • Response validity from JSON-RPC structure

Index

Constants

View Source 
const DefaultEVMArchivalThreshold = 128

128 is the default archival threshold for EVM-based chains. This is an opinionated value that aligns with industry standard practices for defining what constitutes an archival block.

View Source 
const QoSType = "evm"

QoSType is the QoS type for the EVM blockchain.

Variables

This section is empty.

Functions

func NewEVMArchivalCheckConfig 

func NewEVMArchivalCheckConfig(
	contractAddress string,
	contractStartBlock uint64,
) *evmArchivalCheckConfig

Types

type EVMDataExtractor added in v1.0.10 

type EVMDataExtractor struct{}

EVMDataExtractor extracts quality data from EVM JSON-RPC responses. It knows how to parse responses from eth_blockNumber, eth_chainId, eth_syncing, etc.

func NewEVMDataExtractor added in v1.0.10 

func NewEVMDataExtractor() *EVMDataExtractor

NewEVMDataExtractor creates a new EVM data extractor.

func (*EVMDataExtractor) ExtractBlockHeight added in v1.0.10 

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

ExtractBlockHeight extracts the block height from an eth_blockNumber response. The response result is a hex string (e.g., "0x10d4f") which is converted to int64.

Expected response format: 

{"jsonrpc":"2.0","id":1,"result":"0x10d4f"}

Returns:

  • Block height as int64
  • Error if response is invalid or doesn't contain block height

func (*EVMDataExtractor) ExtractChainID added in v1.0.10 

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

ExtractChainID extracts the chain identifier from an eth_chainId response. The chain ID is returned as a hex string (e.g., "0x1" for Ethereum mainnet).

Expected response format: 

{"jsonrpc":"2.0","id":1,"result":"0x1"}

Returns:

  • Chain ID as hex string
  • Error if response is invalid or doesn't contain chain ID

func (*EVMDataExtractor) IsArchival added in v1.0.10 

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

IsArchival determines if the endpoint supports archival queries. This is typically checked by querying historical data (e.g., eth_getBalance at block 1).

An archival node will return a valid result for historical queries. A non-archival node will return an error indicating the block is too old.

Expected response format (archival): 

{"jsonrpc":"2.0","id":1,"result":"0x0"}  // Balance at historical block

Expected response format (non-archival): 

{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"missing trie node..."}}

Returns:

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

func (*EVMDataExtractor) IsSyncing added in v1.0.10 

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

IsSyncing determines if the endpoint is currently syncing from an eth_syncing response.

eth_syncing returns:

  • false: when not syncing (node is fully synced)
  • object: when syncing (contains startingBlock, currentBlock, highestBlock)

Expected response formats: 

{"jsonrpc":"2.0","id":1,"result":false}                    // Not syncing
{"jsonrpc":"2.0","id":1,"result":{"startingBlock":"0x0",...}} // Syncing

Returns:

  • true if endpoint is syncing
  • false if endpoint is synced
  • Error if sync status cannot be determined

func (*EVMDataExtractor) IsValidResponse added in v1.0.10 

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

IsValidResponse checks if the response is a valid JSON-RPC 2.0 response. This performs basic structural validation without extracting specific data.

Checks performed:

  • Valid JSON structure
  • Has "jsonrpc": "2.0"
  • Has either "result" or "error" (not both, not neither)

Returns:

  • true if response is valid JSON-RPC
  • false if response is malformed or contains JSON-RPC error
  • Error if validation fails unexpectedly

type EVMServiceQoSConfig 

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

EVMServiceQoSConfig is the configuration for the EVM service QoS.

func NewEVMServiceQoSConfig 

func NewEVMServiceQoSConfig(
	serviceID protocol.ServiceID,
	evmChainID string,
	archivalCheckConfig *evmArchivalCheckConfig,
	supportedAPIs map[sharedtypes.RPCType]struct{},
) EVMServiceQoSConfig

NewEVMServiceQoSConfig creates a new EVM service configuration with the specified archival check settings.

func NewEVMServiceQoSConfigWithSyncAllowance added in v1.0.10 

func NewEVMServiceQoSConfigWithSyncAllowance(
	serviceID protocol.ServiceID,
	evmChainID string,
	archivalCheckConfig *evmArchivalCheckConfig,
	supportedAPIs map[sharedtypes.RPCType]struct{},
	syncAllowance uint64,
) EVMServiceQoSConfig

NewEVMServiceQoSConfigWithSyncAllowance creates a new EVM service configuration with custom sync allowance.

type EndpointSelectionMetadata 

type EndpointSelectionMetadata struct {
	// RandomEndpointFallback indicates random endpoint selection when all endpoints failed validation
	RandomEndpointFallback bool
	// ValidationResults contains detailed information about each validation attempt (both successful and failed)
	ValidationResults []*qosobservations.EndpointValidationResult
}

EndpointSelectionMetadata contains metadata about the endpoint selection process.

type EndpointSelectionResult 

type EndpointSelectionResult struct {
	// SelectedEndpoint is the chosen endpoint address
	SelectedEndpoint protocol.EndpointAddr
	// Metadata contains endpoint selection process metadata
	Metadata EndpointSelectionMetadata
}

EndpointSelectionResult contains endpoint selection results and metadata.

type QoS 

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

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

  • Request parsing
  • 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 EVM QoS instance without chain-specific validation. Validation (chain ID, archival checks) is now handled by active health checks. This constructor only requires the service ID and provides JSON-RPC request parsing.

func NewSimpleQoSInstanceWithSyncAllowance added in v1.0.10 

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

NewSimpleQoSInstanceWithSyncAllowance creates a minimal EVM QoS instance with custom sync allowance. Validation (chain ID, archival checks) 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 (ss QoS) CheckWebsocketConnection() bool

CheckWebsocketConnection returns true if the endpoint supports Websocket connections.

func (QoS) GetRequiredQualityChecks 

func (ss 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 JSONRPC Returns (errorContext, false) if the request is not valid JSONRPC.

Implements gateway.QoSService interface. Fallback logic for EVM: header → jsonrpc (EVM only supports JSON-RPC)

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

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

SelectMultiple returns multiple endpoint addresses from the list of available endpoints. Available endpoints are filtered based on their validity first. Endpoints are selected with TLD diversity preference when possible. If numEndpoints is 0, it defaults to 1. If numEndpoints is greater than available endpoints, it returns all valid endpoints.

func (QoS) SelectWithMetadata 

func (ss QoS) SelectWithMetadata(availableEndpoints protocol.EndpointAddrList) (EndpointSelectionResult, error)

SelectWithMetadata returns endpoint address and selection metadata. Filters endpoints by validity and captures detailed validation failure information. Selects random endpoint if all fail validation.

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 without blocking user requests.

Implements gateway.QoSService interface.

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.

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.