state

Documentation

Index

• Variables
• type Chain
• type CurrentStakers
• type Diff
  • func NewDiff(parentID ids.ID, stateVersions Versions) (Diff, error)
• type PendingStakers
• type Priority
• type Staker
  • func NewPrimaryNetworkStaker(txID ids.ID, vdr *validator.Validator) *Staker
  • func NewSubnetStaker(txID ids.ID, vdr *validator.SubnetValidator) *Staker
  • func (s *Staker) Less(thanIntf btree.Item) bool
• type StakerDiffIterator
  • func NewStakerDiffIterator(currentIterator, pendingIterator StakerIterator) StakerDiffIterator
• type StakerIterator
  • func NewMaskedIterator(parentIterator StakerIterator, maskedStakers map[ids.ID]*Staker) StakerIterator
  • func NewMergedIterator(stakers ...StakerIterator) StakerIterator
  • func NewTreeIterator(tree *btree.BTree) StakerIterator
• type Stakers
• type State
  • func New(baseDB database.Database, metrics prometheus.Registerer, cfg *config.Config, ...) (State, error)
• type UTXOAdder
• type UTXODeleter
• type UTXOGetter
• type ValidatorWeightDiff
  • func (v *ValidatorWeightDiff) Add(negative bool, amount uint64) error
• type Versions
  • func NewVersions(lastAcceptedID ids.ID, baseState Chain) Versions

Variables

var (
	ErrDelegatorSubset = errors.New("delegator's time range must be a subset of the validator's time range")
)

var PendingToCurrentPriorities = []Priority{
	PrimaryNetworkValidatorPendingPriority: PrimaryNetworkValidatorCurrentPriority,
	PrimaryNetworkDelegatorPendingPriority: PrimaryNetworkDelegatorCurrentPriority,
	SubnetValidatorPendingPriority:         SubnetValidatorCurrentPriority,
	SubnetDelegatorPendingPriority:         SubnetDelegatorCurrentPriority,
}

Types

type Chain

type Chain interface {
	Stakers
	UTXOAdder
	UTXOGetter
	UTXODeleter

	GetTimestamp() time.Time
	SetTimestamp(tm time.Time)
	GetCurrentSupply() uint64
	SetCurrentSupply(cs uint64)

	GetRewardUTXOs(txID ids.ID) ([]*avax.UTXO, error)
	AddRewardUTXO(txID ids.ID, utxo *avax.UTXO)
	GetSubnets() ([]*txs.Tx, error)
	AddSubnet(createSubnetTx *txs.Tx)
	GetChains(subnetID ids.ID) ([]*txs.Tx, error)
	AddChain(createChainTx *txs.Tx)
	GetTx(txID ids.ID) (*txs.Tx, status.Status, error)
	AddTx(tx *txs.Tx, status status.Status)
}

Chain collects all methods to manage the state of the chain for block execution.

type CurrentStakers

type CurrentStakers interface {
	// GetCurrentValidator returns the [staker] describing the validator on
	// [subnetID] with [nodeID]. If the validator does not exist,
	// [database.ErrNotFound] is returned.
	GetCurrentValidator(subnetID ids.ID, nodeID ids.NodeID) (*Staker, error)

	// PutCurrentValidator adds the [staker] describing a validator to the
	// staker set.
	PutCurrentValidator(staker *Staker)

	// DeleteCurrentValidator removes the [staker] describing a validator from
	// the staker set.
	DeleteCurrentValidator(staker *Staker)

	// GetCurrentDelegatorIterator returns the delegators associated with the
	// validator on [subnetID] with [nodeID]. Delegators are sorted by their
	// removal from current staker set.
	GetCurrentDelegatorIterator(subnetID ids.ID, nodeID ids.NodeID) (StakerIterator, error)

	// PutCurrentDelegator adds the [staker] describing a delegator to the
	// staker set.
	PutCurrentDelegator(staker *Staker)

	// DeleteCurrentDelegator removes the [staker] describing a delegator from
	// the staker set.
	DeleteCurrentDelegator(staker *Staker)

	// GetCurrentStakerIterator returns stakers in order of their removal from
	// the current staker set.
	GetCurrentStakerIterator() (StakerIterator, error)
}

type Diff

type Diff interface {
	Chain

	Apply(State)
}

func NewDiff

func NewDiff(
	parentID ids.ID,
	stateVersions Versions,
) (Diff, error)

type PendingStakers

type PendingStakers interface {
	// GetPendingValidator returns the Staker describing the validator on
	// [subnetID] with [nodeID]. If the validator does not exist,
	// [database.ErrNotFound] is returned.
	GetPendingValidator(subnetID ids.ID, nodeID ids.NodeID) (*Staker, error)

	// PutPendingValidator adds the [staker] describing a validator to the
	// staker set.
	PutPendingValidator(staker *Staker)

	// DeletePendingValidator removes the [staker] describing a validator from
	// the staker set.
	DeletePendingValidator(staker *Staker)

	// GetPendingDelegatorIterator returns the delegators associated with the
	// validator on [subnetID] with [nodeID]. Delegators are sorted by their
	// removal from pending staker set.
	GetPendingDelegatorIterator(subnetID ids.ID, nodeID ids.NodeID) (StakerIterator, error)

	// PutPendingDelegator adds the [staker] describing a delegator to the
	// staker set.
	PutPendingDelegator(staker *Staker)

	// DeletePendingDelegator removes the [staker] describing a delegator from
	// the staker set.
	DeletePendingDelegator(staker *Staker)

	// GetPendingStakerIterator returns stakers in order of their removal from
	// the pending staker set.
	GetPendingStakerIterator() (StakerIterator, error)
}

type Priority

type Priority byte

const (
	// First subnet delegators are removed from the current validator set,
	SubnetDelegatorCurrentPriority Priority = iota + 1
	// then subnet validators,
	SubnetValidatorCurrentPriority
	// then primary network delegators,
	PrimaryNetworkDelegatorCurrentPriority
	// then primary network validators.
	PrimaryNetworkValidatorCurrentPriority
)

const (
	// First primary network delegators are moved from the pending to the
	// current validator set,
	PrimaryNetworkDelegatorPendingPriority Priority = iota + 1
	// then primary network validators,
	PrimaryNetworkValidatorPendingPriority
	// then subnet validators,
	SubnetValidatorPendingPriority
	// then subnet delegators.
	SubnetDelegatorPendingPriority
)

type Staker

type Staker struct {
	TxID            ids.ID
	NodeID          ids.NodeID
	SubnetID        ids.ID
	Weight          uint64
	StartTime       time.Time
	EndTime         time.Time
	PotentialReward uint64

	// NextTime is the next time this staker will be moved from a validator set.
	// If the staker is in the pending validator set, NextTime will equal
	// StartTime. If the staker is in the current validator set, NextTime will
	// equal EndTime.
	NextTime time.Time

	// Priority specifies how to break ties between stakers with the same
	// NextTime. This ensures that stakers created by the same transaction type
	// are grouped together. The ordering of these groups is documented in
	// [priorities.go] and depends on if the stakers are in the pending or
	// current validator set.
	Priority Priority
}

Staker contains all information required to represent a validator or delegator in the current and pending validator sets.

func NewPrimaryNetworkStaker

func NewPrimaryNetworkStaker(txID ids.ID, vdr *validator.Validator) *Staker

func NewSubnetStaker

func NewSubnetStaker(txID ids.ID, vdr *validator.SubnetValidator) *Staker

func (*Staker) Less

func (s *Staker) Less(thanIntf btree.Item) bool

A *Staker is considered to be less than another *Staker when:

1. If its NextTime is before the other's.
2. If the NextTimes are the same, the *Staker with the lesser priority is the lesser one.
3. If the priorities are also the same, the one with the lesser txID is lesser.

Invariant: [thanIntf] is a *Staker.

type StakerDiffIterator

type StakerDiffIterator interface {
	Next() bool
	// Returns:
	// - The staker that is changing
	// - True if the staker is being added to the current staker set, false if
	//   the staker is being removed from the current staker set
	Value() (*Staker, bool)
	Release()
}

StakerDiffIterator is an iterator that iterates over the events that will be performed on the current staker set.

There are two event types affecting current staker set, removal of an existing staker and addition of a new staker from the pending set.

The ordering of operations is:

• Staker operations are performed in order of their [NextTime].
• If operations have the same [NextTime], stakers are first added to the current staker set, then removed.
• Further ties are broken by *Staker.Less(), returning the lesser staker first.

func NewStakerDiffIterator

func NewStakerDiffIterator(currentIterator, pendingIterator StakerIterator) StakerDiffIterator

type StakerIterator

type StakerIterator interface {
	// Next attempts to move the iterator to the next staker. It returns false
	// once there are no more stakers to return.
	Next() bool

	// Value returns the current staker. Value should only be called after a
	// call to Next which returned true.
	Value() *Staker

	// Release any resources associated with the iterator. This must be called
	// after the interator is no longer needed.
	Release()
}

StakerIterator defines an interface for iterating over a set of stakers.

var EmptyIterator StakerIterator = emptyIterator{}

EmptyIterator contains no stakers.

func NewMaskedIterator

func NewMaskedIterator(parentIterator StakerIterator, maskedStakers map[ids.ID]*Staker) StakerIterator

NewMaskedIterator returns a new iterator that skips the stakers in [parentIterator] that are present in [maskedStakers].

func NewMergedIterator

func NewMergedIterator(stakers ...StakerIterator) StakerIterator

Returns an iterator that returns all of the elements of [stakers] in order.

func NewTreeIterator

func NewTreeIterator(tree *btree.BTree) StakerIterator

NewTreeIterator returns a new iterator of the stakers in [tree] in ascending order.

type Stakers

type Stakers interface {
	CurrentStakers
	PendingStakers
}

type State

type State interface {
	Chain
	uptime.State
	avax.UTXOReader

	// TODO: remove ShouldInit and DoneInit and perform them in New
	ShouldInit() (bool, error)
	DoneInit() error

	GetLastAccepted() ids.ID
	SetLastAccepted(ids.ID)

	GetValidatorWeightDiffs(height uint64, subnetID ids.ID) (map[ids.NodeID]*ValidatorWeightDiff, error)

	// Return the current validator set of [subnetID].
	ValidatorSet(subnetID ids.ID) (validators.Set, error)

	// SyncGenesis initializes the state with the genesis state.
	SyncGenesis(genesisBlkID ids.ID, genesisState *genesis.State) error

	// Load pulls data previously stored on disk that is expected to be in
	// memory.
	Load() error

	Write(height uint64) error
	Close() error
}

func New

func New(
	baseDB database.Database,
	metrics prometheus.Registerer,
	cfg *config.Config,
	ctx *snow.Context,
	localStake prometheus.Gauge,
	totalStake prometheus.Gauge,
	rewards reward.Calculator,
) (State, error)

type UTXOAdder

type UTXOAdder interface {
	AddUTXO(utxo *avax.UTXO)
}

type UTXODeleter

type UTXODeleter interface {
	DeleteUTXO(utxoID ids.ID)
}

type UTXOGetter

type UTXOGetter interface {
	GetUTXO(utxoID ids.ID) (*avax.UTXO, error)
}

type ValidatorWeightDiff

type ValidatorWeightDiff struct {
	Decrease bool   `serialize:"true"`
	Amount   uint64 `serialize:"true"`
}

func (*ValidatorWeightDiff) Add

func (v *ValidatorWeightDiff) Add(negative bool, amount uint64) error

type Versions

type Versions interface {
	GetState(blkID ids.ID) (Chain, bool)
	SetState(blkID ids.ID, state Chain)
	DeleteState(blkID ids.ID)
}

func NewVersions

func NewVersions(lastAcceptedID ids.ID, baseState Chain) Versions