relayer

Documentation

Index

• func NewRelayMiner(ctx context.Context, deps depinject.Config) (*relayMiner, error)
• type MinedRelay
• type MinedRelaysObservable
• type Miner
• type MinerOption
• type RelayMeter
• type RelayServer
• type RelayerProxy
• type RelayerProxyOption
• type RelayerSessionsManager
• type RelayerSessionsManagerOption
• type RelaysObservable
• type SessionTree

Functions

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 RelayMeter

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

	// VerifyRelayRequest is a shared method used by RelayServers to check the
	// relay request signature and session validity.
	// TODO_TECHDEBT(@red-0ne): This method should be moved out of the RelayerProxy interface
	// that should not be responsible for verifying relay requests.
	VerifyRelayRequest(
		ctx context.Context,
		relayRequest *servicetypes.RelayRequest,
		serviceId string,
	) error

	// SignRelayResponse is a shared method used by RelayServers to sign
	// and append the signature to the RelayResponse.
	// TODO_TECHDEBT(@red-0ne): This method should be moved out of the RelayerProxy interface
	// that should not be responsible for signing relay responses.
	SignRelayResponse(relayResponse *servicetypes.RelayResponse, supplierOperatorAddr string) error
}

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 on-chain. 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 on-chain 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.