state

Documentation

Index

• type MutableProtocolState
  • func NewMutableProtocolState(epochProtocolStateDB storage.ProtocolState, ...) *MutableProtocolState
  • func (s *MutableProtocolState) EvolveState(parentBlockID flow.Identifier, candidateView uint64, ...) (flow.Identifier, *transaction.DeferredBlockPersist, error)
• type ProtocolState
  • func NewProtocolState(epochProtocolStateDB storage.ProtocolState, ...) *ProtocolState
  • func (s *ProtocolState) AtBlockID(blockID flow.Identifier) (protocol.DynamicProtocolState, error)
  • func (s *ProtocolState) GlobalParams() protocol.GlobalParams
  • func (s *ProtocolState) KVStoreAtBlockID(blockID flow.Identifier) (protocol.KVStoreReader, error)

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(
	epochProtocolStateDB storage.ProtocolState,
	kvStoreSnapshots storage.ProtocolKVStore,
	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) EvolveState

func (s *MutableProtocolState) EvolveState(
	parentBlockID flow.Identifier,
	candidateView uint64,
	candidateSeals []*flow.Seal,
) (flow.Identifier, *transaction.DeferredBlockPersist, error)

EvolveState updates the overall Protocol State based on information in the candidate block (potentially still under construction). Information that may change the state is:

• the candidate block's view
• Service Events from execution results sealed in the candidate block

EvolveState is compatible with speculative processing: it evolves an *in-memory copy* of the parent state and collects *deferred database updates* for persisting the resulting Protocol State, including all of its dependencies and respective indices. Though, the resulting batch of deferred database updates still depends on the candidate block's ID, which is still unknown at the time of block construction. Executing the deferred database updates is the caller's responsibility.

SAFETY REQUIREMENTS:

1. The seals must be a protocol-compliant extension of the parent block. Intuitively, we require that the seals follow the ancestry of this fork without gaps. The Consensus Participant's Compliance Layer enforces the necessary constrains. Analogously, the block building logic should always produce protocol-compliant seals. The seals guarantee correctness of the sealed execution result, including the contained service events. This is actively checked by the verification node, whose aggregated approvals in the form of a seal attest to the correctness of the sealed execution result (specifically the Service Events contained in the result and their order).
2. For Consensus Participants that are replicas, the calling code must check that the returned `stateID` matches the commitment in the block proposal! If they don't match, the proposal is byzantine and should be slashed.

Error returns: [TLDR] All error returns indicate potential state corruption and should therefore be treated as fatal.

• Per convention, the input seals from the block payload have already been confirmed to be protocol compliant. Hence, the service events in the sealed execution results represent the honest execution path. Therefore, the sealed service events should encode a valid evolution of the protocol state -- provided the system smart contracts are correct.
• As we can rule out byzantine attacks as the source of failures, the only remaining sources of problems can be (a) bugs in the system smart contracts or (b) bugs in the node implementation. A service event not representing a valid state transition despite all consistency checks passing is interpreted as case (a) and _should be_ handled internally by the respective state machine. Otherwise, any bug or unforeseen edge cases in the system smart contracts would result in consensus halt, due to errors while evolving the protocol state.
• A consistency or sanity check failing within the StateMutator is likely the symptom of an internal bug in the node software or state corruption, i.e. case (b). This is the only scenario where the error return of this function is not nil. If such an exception is returned, continuing is not an option.

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(epochProtocolStateDB storage.ProtocolState, kvStoreSnapshots storage.ProtocolKVStore, globalParams protocol.GlobalParams) *ProtocolState

func (*ProtocolState) AtBlockID

func (s *ProtocolState) AtBlockID(blockID flow.Identifier) (protocol.DynamicProtocolState, error)

AtBlockID returns epoch protocol state at block ID. The resulting epoch protocol state is returned AFTER applying updates that are contained in block. Can be queried for any block that has been added to the block tree. Returns: - (DynamicProtocolState, nil) - if there is an epoch protocol state associated with given block ID. - (nil, storage.ErrNotFound) - if there is no epoch 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.

func (*ProtocolState) KVStoreAtBlockID

func (s *ProtocolState) KVStoreAtBlockID(blockID flow.Identifier) (protocol.KVStoreReader, error)

KVStoreAtBlockID returns protocol state at block ID. The resulting protocol state is returned AFTER applying updates that are contained in block. Can be queried for any block that has been added to the block tree. Returns: - (KVStoreReader, 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.