protocol_state

package
v0.34.0-crescendo-prev... Latest Latest
Warning

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

Go to latest
Published: Mar 18, 2024 License: AGPL-3.0 Imports: 7 Imported by: 2

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type MutableProtocolState

type MutableProtocolState struct {
	ProtocolState
	// contains filtered or unexported fields
}

MutableProtocolState is an implementation of the mutable interface for protocol state, it allows to evolve the protocol state by acting as factory for protocol.StateMutator which can be used to apply state-changing operations.

func NewMutableProtocolState

func NewMutableProtocolState(
	protocolStateDB storage.ProtocolState,
	globalParams protocol.GlobalParams,
	headers storage.Headers,
	results storage.ExecutionResults,
	setups storage.EpochSetups,
	commits storage.EpochCommits,
) *MutableProtocolState

NewMutableProtocolState creates a new instance of MutableProtocolState.

func (*MutableProtocolState) Mutator

func (s *MutableProtocolState) Mutator(candidateView uint64, parentID flow.Identifier) (protocol.StateMutator, error)

Mutator instantiates a `protocol.StateMutator` based on the previous protocol state. Has to be called for each block to evolve the protocol state. Expected errors during normal operations:

  • `storage.ErrNotFound` if no protocol state for parent block is known.

type ProtocolState

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

ProtocolState is an implementation of the read-only interface for protocol state, it allows querying information on a per-block and per-epoch basis. It is backed by a storage.ProtocolState and an in-memory protocol.GlobalParams.

func NewProtocolState

func NewProtocolState(protocolStateDB storage.ProtocolState, globalParams protocol.GlobalParams) *ProtocolState

func (*ProtocolState) AtBlockID

AtBlockID returns protocol state at block ID. Resulting protocol state is returned AFTER applying updates that are contained in block. Returns: - (DynamicProtocolState, nil) - if there is a protocol state associated with given block ID. - (nil, storage.ErrNotFound) - if there is no protocol state associated with given block ID. - (nil, exception) - any other error should be treated as exception.

func (*ProtocolState) GlobalParams

func (s *ProtocolState) GlobalParams() protocol.GlobalParams

GlobalParams returns an interface which can be used to query global protocol parameters.

type ProtocolStateMachine

type ProtocolStateMachine interface {
	// Build returns updated protocol state entry, state ID and a flag indicating if there were any changes.
	// CAUTION:
	// Do NOT call Build, if the ProtocolStateMachine instance has returned a `protocol.InvalidServiceEventError`
	// at any time during its lifetime. After this error, the ProtocolStateMachine is left with a potentially
	// dysfunctional state and should be discarded.
	Build() (updatedState *flow.ProtocolStateEntry, stateID flow.Identifier, hasChanges bool)

	// ProcessEpochSetup updates current protocol state with data from epoch setup event.
	// Processing epoch setup event also affects identity table for current epoch.
	// Observing an epoch setup event, transitions protocol state from staking to setup phase, we stop returning
	// identities from previous+current epochs and start returning identities from current+next epochs.
	// As a result of this operation protocol state for the next epoch will be created.
	// Returned boolean indicates if event triggered a transition in the state machine or not.
	// Implementors must never return (true, error).
	// Expected errors indicating that we are leaving the happy-path of the epoch transitions
	//   - `protocol.InvalidServiceEventError` - if the service event is invalid or is not a valid state transition for the current protocol state.
	//     CAUTION: the protocolStateMachine is left with a potentially dysfunctional state when this error occurs. Do NOT call the Build method
	//     after such error and discard the protocolStateMachine!
	ProcessEpochSetup(epochSetup *flow.EpochSetup) (bool, error)

	// ProcessEpochCommit updates current protocol state with data from epoch commit event.
	// Observing an epoch setup commit, transitions protocol state from setup to commit phase.
	// At this point, we have finished construction of the next epoch.
	// As a result of this operation protocol state for next epoch will be committed.
	// Returned boolean indicates if event triggered a transition in the state machine or not.
	// Implementors must never return (true, error).
	// Expected errors indicating that we are leaving the happy-path of the epoch transitions
	//   - `protocol.InvalidServiceEventError` - if the service event is invalid or is not a valid state transition for the current protocol state.
	//     CAUTION: the protocolStateMachine is left with a potentially dysfunctional state when this error occurs. Do NOT call the Build method
	//     after such error and discard the protocolStateMachine!
	ProcessEpochCommit(epochCommit *flow.EpochCommit) (bool, error)

	// EjectIdentity updates identity table by changing the node's participation status to 'ejected'.
	// Should pass identity which is already present in the table, otherwise an exception will be raised.
	// Expected errors during normal operations:
	// - `protocol.InvalidServiceEventError` if the updated identity is not found in current and adjacent epochs.
	EjectIdentity(nodeID flow.Identifier) error

	// TransitionToNextEpoch discards current protocol state and transitions to the next epoch.
	// Epoch transition is only allowed when:
	// - next epoch has been set up,
	// - next epoch has been committed,
	// - candidate block is in the next epoch.
	// No errors are expected during normal operations.
	TransitionToNextEpoch() error

	// View returns the view that is associated with this ProtocolStateMachine.
	// The view of the ProtocolStateMachine equals the view of the block carrying the respective updates.
	View() uint64

	// ParentState returns parent protocol state that is associated with this ProtocolStateMachine.
	ParentState() *flow.RichProtocolStateEntry
}

ProtocolStateMachine implements a low-level interface for state-changing operations on the protocol state. It is used by higher level logic to evolve the protocol state when certain events that are stored in blocks are observed. The ProtocolStateMachine is stateful and internally tracks the current protocol state. A separate instance is created for each block that is being processed.

type StateMachineFactoryMethod

type StateMachineFactoryMethod = func(candidateView uint64, parentState *flow.RichProtocolStateEntry) (ProtocolStateMachine, error)

StateMachineFactoryMethod is a factory to create state machines for evolving the protocol state. Currently, we have `protocolStateMachine` and `epochFallbackStateMachine` as ProtocolStateMachine implementations, whose constructors both have the same signature as StateMachineFactoryMethod.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL