api

Documentation

Overview

Package api defines the committee scheduler API.

Index

• Constants
• Variables
• type Committee
  • func (c *Committee) String() string
• type CommitteeKind
  • func (k CommitteeKind) MarshalText() ([]byte, error)
  • func (k CommitteeKind) String() string
  • func (k *CommitteeKind) UnmarshalText(text []byte) error
• type CommitteeNode
• type ConsensusParameterChanges
• type ConsensusParameters
• type ElectedEvent
• type ForceElectCommitteeRole
• type Genesis
• type GetCommitteesRequest
• type Role
  • func (r Role) MarshalText() ([]byte, error)
  • func (r Role) String() string
  • func (r *Role) UnmarshalText(text []byte) error
• type Validator
• type VotingPowerDistribution

Constants

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"
)

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"
)

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
)

const ModuleName = "scheduler"

ModuleName is a unique module name for the scheduler module.

Variables

var BaseUnitsPerVotingPower quantity.Quantity

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

Types

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

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

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

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.

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.

type ElectedEvent

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

ElectedEvent is the elected committee kind event.

type ForceElectCommitteeRole

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.

type Genesis

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

Genesis is the committee scheduler 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

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

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

type VotingPowerDistribution uint8

VotingPowerDistribution is the voting power distribution type.