relayer

package
v0.0.13 Latest Latest
Warning

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

 Go to latest Published: Feb 28, 2025 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// RelaysTotal is a Counter metric for the total requests processed by the relay miner.
	// It increments to track proxy requests and is labeled by 'service_id',
	// essential for monitoring load and traffic on different proxies and services.
	//
	// Usage:
	// - Monitor total request load.
	// - Compare requests across services or proxies.
	RelaysTotal = prometheus.NewCounterFrom(stdprometheus.CounterOpts{
		Subsystem: relayMinerProcess,
		Name:      requestsTotal,
		Help:      "Total number of requests processed, labeled by service ID.",
	}, []string{"service_id", "supplier_operator_address"})

	// RelaysErrorsTotal is a Counter for total error events in the relay miner.
	// It increments with each error, labeled by 'service_id',
	// crucial for pinpointing error-prone areas for reliability improvement.
	//
	// Usage:
	// - Track and analyze error types and distribution.
	// - Compare error rates for reliability analysis.
	RelaysErrorsTotal = prometheus.NewCounterFrom(stdprometheus.CounterOpts{
		Subsystem: relayMinerProcess,
		Name:      requestsErrorsTotal,
		Help:      "Total number of error events.",
	}, []string{"service_id"})

	// RelaysSuccessTotal is a Counter metric for successful requests in the relay miner.
	// It increments with each successful request, labeled by 'service_id'.
	RelaysSuccessTotal = prometheus.NewCounterFrom(stdprometheus.CounterOpts{
		Subsystem: relayMinerProcess,
		Name:      requestsSuccessTotal,
		Help:      "Total number of successful requests processed, labeled by service ID.",
	}, []string{"service_id"})

	// RelaysDurationSeconds observes request durations in the relay miner.
	// This histogram, labeled by 'service_id', measures response times,
	// vital for performance analysis under different loads.
	//
	// Buckets:
	// - 0.1s to 15s range, capturing response times from very fast to upper limit.
	//
	// Usage:
	// - Analyze typical response times and long-tail latency issues.
	// - Compare performance across services or environments.
	RelaysDurationSeconds = prometheus.NewHistogramFrom(stdprometheus.HistogramOpts{
		Subsystem: relayMinerProcess,
		Name:      relayDurationSeconds,
		Help:      "Histogram of request durations for performance analysis.",
		Buckets:   []float64{0.1, 0.5, 1, 2, 5, 15},
	}, []string{"service_id"})

	// RelayResponseSizeBytes is a histogram metric for observing response size distribution.
	// It counts responses in bytes, with buckets:
	// - 100 bytes to 50,000 bytes, capturing a range from small to large responses.
	// This data helps in accurately representing response size distribution and is vital
	// for performance tuning.
	//
	// TODO_TECHDEBT: Consider configuring bucket sizes externally for flexible adjustments
	// in response to different data patterns or deployment scenarios.
	RelayResponseSizeBytes = prometheus.NewHistogramFrom(stdprometheus.HistogramOpts{
		Subsystem: relayMinerProcess,
		Name:      responseSizeBytes,
		Help:      "Histogram of response sizes in bytes for performance analysis.",
		Buckets:   []float64{100, 500, 1000, 5000, 10000, 50000},
	}, []string{"service_id"})

	// RelayRequestSizeBytes is a histogram metric for observing request size distribution.
	// It counts requests in bytes, with buckets:
	// - 100 bytes to 50,000 bytes, capturing a range from small to large requests.
	// This data helps in accurately representing request size distribution and is vital
	// for performance tuning.
	RelayRequestSizeBytes = prometheus.NewHistogramFrom(stdprometheus.HistogramOpts{
		Subsystem: relayMinerProcess,
		Name:      requestSizeBytes,
		Help:      "Histogram of request sizes in bytes for performance analysis.",
		Buckets:   []float64{100, 500, 1000, 5000, 10000, 50000},
	}, []string{"service_id"})
)

Functions

func BuildServiceBackendRequest added in v0.0.13 

func BuildServiceBackendRequest(
	relayRequest *types.RelayRequest,
	serviceConfig *config.RelayMinerSupplierServiceConfig,
) (*http.Request, error)

BuildServiceBackendRequest builds the service backend request from the relay request and the service configuration.

func NewRelayMiner 

func NewRelayMiner(ctx context.Context, deps depinject.Config) (*relayMiner, error)

NewRelayMiner creates a new Relayer instance with the given dependencies. It injects the dependencies into the Relayer instance and returns it.

Required dependencies:

  • RelayerProxy
  • Miner
  • RelayerSessionsManager

Types

type MinedRelay 

type MinedRelay struct {
	types.Relay
	Bytes []byte
	Hash  []byte
}

MinedRelay is a wrapper around a relay that has been serialized and hashed.

type MinedRelaysObservable 

type MinedRelaysObservable observable.Observable[*MinedRelay]

MinedRelaysObservable is an observable which is notified with MinedRelay values.

TODO_HACK: The purpose of this type is to work around gomock's lack of support for generic types. For the same reason, this type cannot be an alias (i.e. MinedRelaysObservable = observable.Observable[*MinedRelay]).

type Miner 

type Miner interface {
	MinedRelays(
		ctx context.Context,
		servedRelayObs RelaysObservable,
	) (minedRelaysObs MinedRelaysObservable)
}

Miner is responsible for observing servedRelayObs, hashing and checking the difficulty of each, finally publishing those with sufficient difficulty to minedRelayObs as they are applicable for relay volume.

type MinerOption 

type MinerOption func(Miner)

type RelayAuthenticator added in v0.0.13 

type RelayAuthenticator interface {
	// VerifyRelayRequest verifies the relay request signature and session validity.
	VerifyRelayRequest(
		ctx context.Context,
		relayRequest *servicetypes.RelayRequest,
		serviceId string,
	) error

	// SignRelayResponse signs the relay response given a supplier operator address.
	SignRelayResponse(relayResponse *servicetypes.RelayResponse, supplierOperatorAddr string) error

	// GetSupplierOperatorAddresses returns the supplier operator addresses that
	// the relay authenticator can use to sign relay responses.
	GetSupplierOperatorAddresses() []string

	// Start starts the relay authenticator and its underlying services.
	Start(ctx context.Context)
}

RelayAuthenticator is the interface that authenticates the relay requests and responses (i.e. verifies the relay request signature and session validity, and signs the relay response).

type RelayAuthenticatorOption added in v0.0.13 

type RelayAuthenticatorOption func(RelayAuthenticator)

type RelayMeter added in v0.0.11 

type RelayMeter interface {
	// Start starts the relay meter.
	Start(ctx context.Context) error

	// AccumulateRelayReward adds the relay reward from the incoming request to session's accumulator.
	// The relay cost is added optimistically, assuming that the relay WILL be volume / reward applicable.
	//
	// The reason why optimistic AccumulateRelayReward + SetNonApplicableRelayReward is used instead of
	// a simpler AccumulateVolumeApplicableRelayReward is that when the relay is first seen
	// we don't know if it will be volume / reward applicable until it is served.
	//
	// To rate limit or not the current relay, we need to always optimistically account all relays as being
	// volume / reward applicable.
	AccumulateRelayReward(ctx context.Context, relayRequestMeta servicetypes.RelayRequestMetadata) error

	// SetNonApplicableRelayReward updates the relay meter for the given relay request as
	// non-applicable between a single Application and a single Supplier for a single session.
	// The volume / reward applicability of the relay is unknown to the relay miner
	// until the relay is served and the relay response signed.
	SetNonApplicableRelayReward(ctx context.Context, relayRequestMeta servicetypes.RelayRequestMetadata) error
}

RelayMeter is an interface that keeps track of the amount of stake consumed between a single onchain Application and a single onchain Supplier over the course of a single session. It enables the RelayMiner to rate limit the number of requests handled offchain as a function of the optimistic onchain rate limits.

type RelayServer 

type RelayServer interface {
	// Start starts the service server and returns an error if it fails.
	Start(ctx context.Context) error

	// Stop terminates the service server and returns an error if it fails.
	Stop(ctx context.Context) error
}

RelayServer is the interface of the advertised relay servers provided by the RelayerProxy.

type RelayerProxy 

type RelayerProxy interface {
	// Start starts all advertised relay servers and returns an error if any of them fail to start.
	Start(ctx context.Context) error

	// Stop stops all advertised relay servers and returns an error if any of them fail.
	Stop(ctx context.Context) error

	// ServedRelays returns an observable that notifies the miner about the relays that have been served.
	// A served relay is one whose RelayRequest's signature and session have been verified,
	// and its RelayResponse has been signed and successfully sent to the client.
	ServedRelays() RelaysObservable
}

RelayerProxy is the interface for the proxy that serves relays to the application. It is responsible for starting and stopping all supported RelayServers. While handling requests and responding in a closed loop, it also notifies the miner about the relays that have been served.

type RelayerProxyOption 

type RelayerProxyOption func(RelayerProxy)

type RelayerSessionsManager 

type RelayerSessionsManager interface {
	// InsertRelays receives an observable of relays that should be included
	// in their respective session's SMST (tree).
	InsertRelays(minedRelaysObs MinedRelaysObservable)

	// Start iterates over the session trees at the end of each, respective, session.
	// The session trees are piped through a series of map operations which progress
	// them through the claim/proof lifecycle, broadcasting transactions to  the
	// network as necessary.
	Start(ctx context.Context)

	// Stop unsubscribes all observables from the InsertRelays observable which
	// will close downstream observables as they drain.
	//
	// TODO_TECHDEBT: Either add a mechanism to wait for draining to complete
	// and/or ensure that the state at each pipeline stage is persisted to disk
	// and exit as early as possible.
	Stop()
}

RelayerSessionsManager is responsible for managing the relayer's session lifecycles. It handles the creation and retrieval of SMSTs (trees) for a given session, as well as the respective and subsequent claim creation and proof submission. This is largely accomplished by pipelining observables of relays and sessions through a series of map operations.

TODO_TECHDEBT: add architecture diagrams covering observable flows throughout the relayer package.

type RelayerSessionsManagerOption 

type RelayerSessionsManagerOption func(RelayerSessionsManager)

type RelaysObservable 

type RelaysObservable observable.Observable[*servicetypes.Relay]

RelaysObservable is an observable which is notified with Relay values.

TODO_HACK: The purpose of this type is to work around gomock's lack of support for generic types. For the same reason, this type cannot be an alias (i.e. RelaysObservable = observable.Observable[*servicetypes.Relay]).

type SessionTree 

type SessionTree interface {
	// GetSessionHeader returns the header of the session corresponding to the SMST.
	GetSessionHeader() *sessiontypes.SessionHeader

	// Update is a wrapper for the SMST's Update function. It updates the SMST with
	// the given key, value, and weight.
	// This function should be called when a Relay has been successfully served.
	Update(key, value []byte, weight uint64) error

	// ProveClosest is a wrapper for the SMST's ProveClosest function. It returns the
	// proof for the given path.
	// This function should be called several blocks after a session has been claimed and needs to be proven.
	ProveClosest(path []byte) (proof *smt.SparseCompactMerkleClosestProof, err error)

	// GetClaimRoot returns the root hash of the SMST needed for creating the claim.
	GetClaimRoot() []byte

	// GetProofBz returns the proof created by ProveClosest needed for submitting
	// a proof in byte format.
	GetProofBz() []byte

	// Flush gets the root hash of the SMST needed for submitting the claim;
	// then commits the entire tree to disk and stops the KVStore.
	// It should be called before submitting the claim onchain. This function frees up
	// the in-memory resources used by the SMST that are no longer needed while waiting
	// for the proof submission window to open.
	Flush() (SMSTRoot []byte, err error)

	// TODO_DISCUSS: This function should not be part of the interface as it is an optimization
	// aiming to free up KVStore resources after the proof is no longer needed.
	// Delete deletes the SMST from the KVStore.
	// WARNING: This function should be called only after the proof has been successfully
	// submitted onchain and the servicer has confirmed that it has been rewarded.
	Delete() error

	// StartClaiming marks the session tree as being picked up for claiming,
	// so it won't be picked up by the relayer again.
	// It returns an error if it has already been marked as such.
	StartClaiming() error

	// GetSupplierOperatorAddress returns the supplier operator address building this tree.
	GetSupplierOperatorAddress() *cosmostypes.AccAddress

	// GetTrieSpec returns the trie spec of the SMST.
	GetTrieSpec() smt.TrieSpec
}

SessionTree is an interface that wraps an SMST (Sparse Merkle State Trie) and its corresponding session.

Source Files

View all Source files

Directories

Path Synopsis
websockets

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.