relayer

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

type MinedRelaysObservable observable.Observable[*MinedRelay]

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

type MinerOption func(Miner)

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
}

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
}

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
}

type RelayerProxyOption func(RelayerProxy)

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()
}

type RelayerSessionsManagerOption func(RelayerSessionsManager)

type RelaysObservable observable.Observable[*servicetypes.Relay]

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
}