scores

Documentation

Index

• Constants
• Variables
• func CalcGeoCost(reqGeo planstypes.Geolocation, providerGeos []planstypes.Geolocation) (minLatencyGeo planstypes.Geolocation, minLatencyCost math.Uint)
• func CalcPairingScore(scores []*PairingScore, strategy ScoreStrategy, diffSlot *PairingSlot) error
• func PickProviders(ctx sdk.Context, scores []*PairingScore, groupCount int, hashData []byte) (returnedProviders []epochstoragetypes.StakeEntry)
• func PrepareHashData(projectIndex, chainID string, epochHash []byte, idx int) []byte
• type GeoLatency
• type GeoReq
  • func (gr GeoReq) Equal(other ScoreReq) bool
  • func (gr GeoReq) GetName() string
  • func (gr GeoReq) GetReqForSlot(policy planstypes.Policy, slotIdx int) ScoreReq
  • func (gr GeoReq) Init(policy planstypes.Policy) bool
  • func (gr GeoReq) Score(provider epochstoragetypes.StakeEntry) math.Uint
• type PairingScore
  • func NewPairingScore(stakeEntry *epochstoragetypes.StakeEntry) *PairingScore
• type PairingSlot
  • func CalcSlots(policy planstypes.Policy) []*PairingSlot
  • func GroupSlots(slots []*PairingSlot) []*PairingSlot
  • func NewPairingSlot() *PairingSlot
  • func (s PairingSlot) Equal(other *PairingSlot) bool
  • func (s PairingSlot) Subtract(other *PairingSlot) *PairingSlot
• type ScoreReq
  • func GetAllReqs() []ScoreReq
• type ScoreStrategy
  • func GetStrategy() ScoreStrategy
• type StakeReq
  • func (sr *StakeReq) Equal(other ScoreReq) bool
  • func (sr *StakeReq) GetName() string
  • func (sr *StakeReq) GetReqForSlot(policy planstypes.Policy, slotIdx int) ScoreReq
  • func (sr *StakeReq) Init(policy planstypes.Policy) bool
  • func (sr *StakeReq) Score(stakeEntry epochstoragetypes.StakeEntry) math.Uint

Constants

const (
	// TODO: temp strategy weight until we implement taking it out of the policy
	UNIFORM_WEIGHT uint64 = 1
)

Variables

var GEO_LATENCY_MAP = map[planstypes.Geolocation]map[planstypes.Geolocation]uint64{
	planstypes.Geolocation_AS: {
		planstypes.Geolocation_AU: 146,
		planstypes.Geolocation_EU: 155,
	},
	planstypes.Geolocation_USE: {
		planstypes.Geolocation_USC: 42,
		planstypes.Geolocation_USW: 68,
	},
	planstypes.Geolocation_USW: {
		planstypes.Geolocation_USC: 45,
		planstypes.Geolocation_USE: 68,
	},
	planstypes.Geolocation_USC: {
		planstypes.Geolocation_USE: 42,
		planstypes.Geolocation_USW: 45,
	},
	planstypes.Geolocation_EU: {
		planstypes.Geolocation_USE: 116,
		planstypes.Geolocation_AF:  138,
		planstypes.Geolocation_AS:  155,
	},
	planstypes.Geolocation_AF: {
		planstypes.Geolocation_EU:  138,
		planstypes.Geolocation_USE: 203,
		planstypes.Geolocation_AS:  263,
	},
	planstypes.Geolocation_AU: {
		planstypes.Geolocation_AS:  146,
		planstypes.Geolocation_USW: 179,
	},
}

GEO_LATENCY_MAP is a map of lists of GeoLatency that defines the cost of geo mismatch for each single geolocation. The map key is a single geolocation and the value is an ordered list of neighbors and their latency (ordered by latency) latency data from: https://wondernetwork.com/pings (July 2023)

Functions

func CalcGeoCost

func CalcGeoCost(reqGeo planstypes.Geolocation, providerGeos []planstypes.Geolocation) (minLatencyGeo planstypes.Geolocation, minLatencyCost math.Uint)

CalcGeoCost() finds the minimal latency between the required geo and the provider's supported geolocations

func CalcPairingScore

func CalcPairingScore(scores []*PairingScore, strategy ScoreStrategy, diffSlot *PairingSlot) error

CalcPairingScore calculates the final pairing score for a pairing slot (with strategy) For efficiency purposes, we calculate the score on a diff slot which represents the diff reqs of the current slot and the previous slot

func PickProviders

func PickProviders(ctx sdk.Context, scores []*PairingScore, groupCount int, hashData []byte) (returnedProviders []epochstoragetypes.StakeEntry)

PickProviders pick a <group-count> providers set with a pseudo-random weighted choice (using the providers' score list and hashData)

func PrepareHashData

func PrepareHashData(projectIndex, chainID string, epochHash []byte, idx int) []byte

PrepareHashData prepares the hash needed in the pseudo-random choice of providers

Types

type GeoLatency

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

a single geolocation and the latency to it (in millieseconds)

type GeoReq

type GeoReq struct {
	Geo uint64
}

geo requirement that implements the ScoreReq interface

func (GeoReq) Equal

func (gr GeoReq) Equal(other ScoreReq) bool

Equal() used to compare slots to determine slot groups

func (GeoReq) GetName

func (gr GeoReq) GetName() string

func (GeoReq) GetReqForSlot

func (gr GeoReq) GetReqForSlot(policy planstypes.Policy, slotIdx int) ScoreReq

TODO: this function doesn't return the optimal geo reqs for the case that there are more required geos than providers to pair

func (GeoReq) Init

func (gr GeoReq) Init(policy planstypes.Policy) bool

func (GeoReq) Score

func (gr GeoReq) Score(provider epochstoragetypes.StakeEntry) math.Uint

Score calculates the geo score of a provider based on preset latency data Note: each GeoReq must have exactly a single geolocation (bit)

type PairingScore

type PairingScore struct {
	Provider         *epochstoragetypes.StakeEntry
	Score            math.Uint
	ScoreComponents  map[string]math.Uint
	SkipForSelection bool
}

PairingScore holds a provider's score with respect to a set of requirements (ScoreReq), indexed by their unique name.

func NewPairingScore

func NewPairingScore(stakeEntry *epochstoragetypes.StakeEntry) *PairingScore

type PairingSlot

type PairingSlot struct {
	Reqs  map[string]ScoreReq
	Count int
}

PairingSlot holds the set of requirements for a slot. It also holds the number of identical slots required for the pairing (count)

func CalcSlots

func CalcSlots(policy planstypes.Policy) []*PairingSlot

get the overall requirements from the policy and assign slots that'll fulfil them TODO: this function should be changed in the future since it only supports stake reqs

func GroupSlots

func GroupSlots(slots []*PairingSlot) []*PairingSlot

group the slots

func NewPairingSlot

func NewPairingSlot() *PairingSlot

func (PairingSlot) Equal

func (s PairingSlot) Equal(other *PairingSlot) bool

func (PairingSlot) Subtract

func (s PairingSlot) Subtract(other *PairingSlot) *PairingSlot

Subtract generates a diff slot that contains the reqs that are in the slot receiver but not in the "other" slot

type ScoreReq

type ScoreReq interface {
	// Init() initializes the ScoreReq object and returns whether it's active
	Init(policy planstypes.Policy) bool
	// Score() calculates a provider's score according to the requirement
	Score(stakeEntry epochstoragetypes.StakeEntry) math.Uint
	// GetName returns the unique name of the ScoreReq implementation
	GetName() string
	// Equal compares two ScoreReq objects
	Equal(other ScoreReq) bool
	// GetReqForSlot gets ScoreReq for slot by its index
	GetReqForSlot(policy planstypes.Policy, slotIdx int) ScoreReq
}

ScoreReq is an interface for pairing requirement scoring

func GetAllReqs

func GetAllReqs() []ScoreReq

type ScoreStrategy

type ScoreStrategy map[string]uint64

map: key: ScoreReq name, value: weight in the final pairing score

func GetStrategy

func GetStrategy() ScoreStrategy

TODO: currently we'll use weight=1 for all reqs. In the future, we'll get it from policy

type StakeReq

type StakeReq struct{}

StakeReq implements the ScoreReq interface for provider staking requirement(s)

func (*StakeReq) Equal

func (sr *StakeReq) Equal(other ScoreReq) bool

Equal used to compare slots to determine slot groups. Equal always returns true (StakeReq score of an entry is the entry's stake)

func (*StakeReq) GetName

func (sr *StakeReq) GetName() string

func (*StakeReq) GetReqForSlot

func (sr *StakeReq) GetReqForSlot(policy planstypes.Policy, slotIdx int) ScoreReq

func (*StakeReq) Init

func (sr *StakeReq) Init(policy planstypes.Policy) bool

func (*StakeReq) Score

func (sr *StakeReq) Score(stakeEntry epochstoragetypes.StakeEntry) math.Uint

Score calculates the the provider score as the normalized stake