api

package
v0.2300.0 Latest Latest
Warning

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

 Go to latest Published: Oct 10, 2023 License: Apache-2.0 Imports: 13 Imported by: 13

Documentation

Overview

Package api defines the committee scheduler API.

Index

Constants

View Source 
const (
	// RoleInvalid is an invalid role (should never appear on the wire).
	RoleInvalid Role = 0
	// RoleWorker indicates the node is a worker.
	RoleWorker Role = 1
	// RoleBackupWorker indicates the node is a backup worker.
	RoleBackupWorker Role = 2

	RoleInvalidName      = "invalid"
	RoleWorkerName       = "worker"
	RoleBackupWorkerName = "backup-worker"
)
View Source 
const (
	// KindInvalid is an invalid committee.
	KindInvalid CommitteeKind = 0
	// KindComputeExecutor is an executor committee.
	KindComputeExecutor CommitteeKind = 1

	// MaxCommitteeKind is a dummy value used for iterating all committee kinds.
	MaxCommitteeKind = 2

	KindInvalidName         = "invalid"
	KindComputeExecutorName = "executor"
)
View Source 
const (
	// VotingPowerDistributionLinear is the distribution where power is
	// linearly proportional to the stake.
	VotingPowerDistributionLinear = 0
	// VotingPowerDistributionSqrt is the distribution where power is
	// proportional to the square root of the stake.
	VotingPowerDistributionSqrt = 1
)
View Source 
const ModuleName = "scheduler"

ModuleName is a unique module name for the scheduler module.

Variables

View Source 
var BaseUnitsPerVotingPower quantity.Quantity

BaseUnitsPerVotingPower is the ratio of base units staked to validator power.

Functions

func RegisterService 

func RegisterService(server *grpc.Server, service Backend)

RegisterService registers a new scheduler service with the given gRPC server.

func VotingPowerFromStake 

func VotingPowerFromStake(t *quantity.Quantity, distribution VotingPowerDistribution) (int64, error)

VotingPowerFromStake computes the voting power from given stake based on the given distribution.

NOTE: It's not that we're implementation-hiding the conversion though. It's just that otherwise if we accidentally skip the `IsInt64`, it would still appear to work, and that would be a bad thing to have in a routine that's written multiple times.

Types

type Backend 

type Backend interface {
	// GetValidators returns the vector of consensus validators for
	// a given epoch.
	GetValidators(ctx context.Context, height int64) ([]*Validator, error)

	// GetCommittees returns the vector of committees for a given
	// runtime ID, at the specified block height, and optional callback
	// for querying the beacon for a given epoch/block height.
	//
	// Iff the callback is nil, `beacon.GetBlockBeacon` will be used.
	GetCommittees(ctx context.Context, request *GetCommitteesRequest) ([]*Committee, error)

	// WatchCommittees returns a channel that produces a stream of
	// Committee.
	//
	// Upon subscription, all committees for the current epoch will
	// be sent immediately.
	WatchCommittees(ctx context.Context) (<-chan *Committee, pubsub.ClosableSubscription, error)

	// StateToGenesis returns the genesis state at specified block height.
	StateToGenesis(ctx context.Context, height int64) (*Genesis, error)

	// ConsensusParameters returns the scheduler consensus parameters.
	ConsensusParameters(ctx context.Context, height int64) (*ConsensusParameters, error)

	// Cleanup cleans up the scheduler backend.
	Cleanup()
}

Backend is a scheduler implementation.

func NewSchedulerClient 

func NewSchedulerClient(c *grpc.ClientConn) Backend

NewSchedulerClient creates a new gRPC scheduler client service.

type Committee 

type Committee struct {
	// Kind is the functionality a committee exists to provide.
	Kind CommitteeKind `json:"kind"`

	// Members is a collection of committee members.
	//
	// The order of committee members is consistent, with workers always preceding backup workers.
	Members []*CommitteeNode `json:"members"`

	// RuntimeID is the runtime ID that this committee is for.
	RuntimeID common.Namespace `json:"runtime_id"`

	// ValidFor is the epoch for which the committee is valid.
	ValidFor beacon.EpochTime `json:"valid_for"`
}

Committee is a per-runtime (instance) committee.

func (*Committee) EncodedMembersHash 

func (c *Committee) EncodedMembersHash() hash.Hash

EncodedMembersHash returns the encoded cryptographic hash of the committee members.

func (*Committee) IsBackupWorker added in v0.2300.0 

func (c *Committee) IsBackupWorker(id signature.PublicKey) bool

IsBackupWorker returns true iff the given node is a backup worker in the committee.

func (*Committee) IsMember added in v0.2300.0 

func (c *Committee) IsMember(id signature.PublicKey) bool

IsMember returns true iff the given node is a member of the committee.

func (*Committee) IsWorker added in v0.2300.0 

func (c *Committee) IsWorker(id signature.PublicKey) bool

IsWorker returns true iff the given node is a worker in the committee.

func (*Committee) Scheduler added in v0.2300.0 

func (c *Committee) Scheduler(round uint64, rank uint64) (*CommitteeNode, bool)

Scheduler returns the scheduler with the given rank in the committee's scheduling order for the given round.

If no scheduler with the given rank is found, it returns false.

func (*Committee) SchedulerIdx added in v0.2300.0 

func (c *Committee) SchedulerIdx(round uint64, rank uint64) (int, bool)

SchedulerIdx returns the index of the scheduler with the given rank in the committee's scheduling order for the given round.

If no scheduler with the given rank is found, it returns false.

func (*Committee) SchedulerRank added in v0.2300.0 

func (c *Committee) SchedulerRank(round uint64, id signature.PublicKey) (uint64, bool)

SchedulerRank returns the position (index) of a node with the given public key in the committee's scheduling order for the given round. A lower rank indicates higher scheduling priority.

If the node is not a worker in the committee and, therefore, not allowed to schedule transactions for the given round, it returns false.

func (*Committee) String 

func (c *Committee) String() string

String returns a string representation of a Committee.

type CommitteeKind 

type CommitteeKind uint8

CommitteeKind is the functionality a committee exists to provide.

func (CommitteeKind) MarshalText added in v0.2100.0 

func (k CommitteeKind) MarshalText() ([]byte, error)

MarshalText encodes a CommitteeKind into text form.

func (CommitteeKind) String 

func (k CommitteeKind) String() string

String returns a string representation of a CommitteeKind.

func (*CommitteeKind) UnmarshalText added in v0.2100.0 

func (k *CommitteeKind) UnmarshalText(text []byte) error

UnmarshalText decodes a text slice into a CommitteeKind.

type CommitteeNode 

type CommitteeNode struct {
	// Role is the node's role in a committee.
	Role Role `json:"role"`

	// PublicKey is the node's public key.
	PublicKey signature.PublicKey `json:"public_key"`
}

CommitteeNode is a node participating in a committee.

type ConsensusParameterChanges added in v0.2202.0 

type ConsensusParameterChanges struct {
	// MinValidators is the new minimum number of validators.
	MinValidators *int `json:"min_validators"`

	// MaxValidators is the new maximum number of validators.
	MaxValidators *int `json:"max_validators"`

	// VotingPowerDistribution is the new voting power distribution.
	VotingPowerDistribution *VotingPowerDistribution `json:"voting_power_distribution,omitempty"`
}

ConsensusParameterChanges are allowed scheduler consensus parameter changes.

func (*ConsensusParameterChanges) Apply added in v0.2202.0 

func (c *ConsensusParameterChanges) Apply(params *ConsensusParameters) error

Apply applies changes to the given consensus parameters.

func (*ConsensusParameterChanges) SanityCheck added in v0.2202.0 

func (c *ConsensusParameterChanges) SanityCheck() error

SanityCheck performs a sanity check on the consensus parameter changes.

type ConsensusParameters 

type ConsensusParameters struct {
	// MinValidators is the minimum number of validators that MUST be
	// present in elected validator sets.
	MinValidators int `json:"min_validators"`

	// MaxValidators is the maximum number of validators that MAY be
	// present in elected validator sets.
	MaxValidators int `json:"max_validators"`

	// MaxValidatorsPerEntity is the maximum number of validators that
	// may be elected per entity in a single validator set.
	MaxValidatorsPerEntity int `json:"max_validators_per_entity"`

	// DebugBypassStake is true iff the scheduler should bypass all of
	// the staking related checks and operations.
	DebugBypassStake bool `json:"debug_bypass_stake,omitempty"`

	// RewardFactorEpochElectionAny is the factor for a reward
	// distributed per epoch to entities that have any node considered
	// in any election.
	RewardFactorEpochElectionAny quantity.Quantity `json:"reward_factor_epoch_election_any"`

	// DebugForceElect is the map of nodes that will always be elected
	// to a given role for a runtime.
	DebugForceElect map[common.Namespace]map[signature.PublicKey]*ForceElectCommitteeRole `json:"debug_force_elect,omitempty"`

	// DebugAllowWeakAlpha allows VRF based elections based on proofs
	// generated by an alpha value considered weak.
	DebugAllowWeakAlpha bool `json:"debug_allow_weak_alpha,omitempty"`

	// VotingPowerDistribution is the voting power distribution.
	VotingPowerDistribution VotingPowerDistribution `json:"voting_power_distribution,omitempty"`
}

ConsensusParameters are the scheduler consensus parameters.

func (*ConsensusParameters) SanityCheck added in v0.2202.0 

func (p *ConsensusParameters) SanityCheck() error

SanityCheck performs a sanity check on the consensus parameters.

type ElectedEvent added in v0.2200.0 

type ElectedEvent struct {
	// Kinds are the elected committee kinds.
	Kinds []CommitteeKind `json:"kinds,omitempty"`
}

ElectedEvent is the elected committee kind event.

func (*ElectedEvent) EventKind added in v0.2200.0 

func (ev *ElectedEvent) EventKind() string

EventKind returns a string representation of this event's kind.

type ForceElectCommitteeRole added in v0.2200.0 

type ForceElectCommitteeRole struct {
	// Kind is the kind of committee to force-elect the node into.
	Kind CommitteeKind `json:"kind,omitempty"`
	// Roles are the roles that the given node is force elected as.
	Roles []Role `json:"roles,omitempty"`
	// Index is the position of the given node in the committee's worker group if it has
	// the worker role.
	Index uint64 `json:"index,omitempty"`
}

ForceElectCommitteeRole is the committee kind/role that a force-elected node is elected as.

func (*ForceElectCommitteeRole) HasRole added in v0.2202.0 

func (fe *ForceElectCommitteeRole) HasRole(role Role) bool

HasRole returns true whether the force election configuration specifies a given role.

type Genesis 

type Genesis struct {
	// Parameters are the scheduler consensus parameters.
	Parameters ConsensusParameters `json:"params"`
}

Genesis is the committee scheduler genesis state.

func (*Genesis) SanityCheck 

func (g *Genesis) SanityCheck(stakingTotalSupply *quantity.Quantity, votingPowerDistribution VotingPowerDistribution) error

SanityCheck does basic sanity checking on the genesis state.

type GetCommitteesRequest 

type GetCommitteesRequest struct {
	Height    int64            `json:"height"`
	RuntimeID common.Namespace `json:"runtime_id"`
}

GetCommitteesRequest is a GetCommittees request.

type Role 

type Role uint8

Role is the role a given node plays in a committee.

func (Role) MarshalText added in v0.2010.0 

func (r Role) MarshalText() ([]byte, error)

MarshalText encodes a Role into text form.

func (Role) String 

func (r Role) String() string

String returns a string representation of a Role.

func (*Role) UnmarshalText added in v0.2010.0 

func (r *Role) UnmarshalText(text []byte) error

UnmarshalText decodes a text slice into a Role.

type Validator 

type Validator struct {
	// ID is the validator Oasis node identifier.
	ID signature.PublicKey `json:"id"`

	// EntityID is the validator entity identifier.
	EntityID signature.PublicKey `json:"entity_id"`

	// VotingPower is the validator's consensus voting power.
	VotingPower int64 `json:"voting_power"`
}

Validator is a consensus validator.

type VotingPowerDistribution added in v0.2300.0 

type VotingPowerDistribution uint8

VotingPowerDistribution is the voting power distribution type.

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.