badger

package
v0.37.0-crescendo-RC4 Latest Latest
Warning

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

 Go to latest Published: Aug 8, 2024 License: AGPL-3.0 Imports: 30 Imported by: 12

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsBootstrapped added in v0.14.0 

func IsBootstrapped(db *badger.DB) (bool, error)

IsBootstrapped returns whether the database contains a bootstrapped state

func IsValidRootSnapshot added in v0.23.9 

func IsValidRootSnapshot(snap protocol.Snapshot, verifyResultID bool) error

IsValidRootSnapshot checks internal consistency of root state snapshot if verifyResultID allows/disallows Result ID verification

func IsValidRootSnapshotQCs added in v0.25.0 

func IsValidRootSnapshotQCs(snap protocol.Snapshot) error

IsValidRootSnapshotQCs checks internal consistency of QCs that are included in the root state snapshot It verifies QCs for main consensus and for each collection cluster.

func ReadFinalizedRoot added in v0.33.30 

func ReadFinalizedRoot(db *badger.DB) (*flow.Header, error)

ReadFinalizedRoot retrieves the root block's header from the database. This information is immutable for the runtime of the software and may be cached.

func ReadGlobalParams added in v0.33.30 

func ReadGlobalParams(db *badger.DB) (*inmem.Params, error)

ReadGlobalParams reads the global parameters from the database and returns them as in-memory representation. No errors are expected during normal operation.

func SkipNetworkAddressValidation added in v0.22.0 

func SkipNetworkAddressValidation(conf *BootstrapConfig)

func ValidRootSnapshotContainsEntityExpiryRange added in v0.29.9 

func ValidRootSnapshotContainsEntityExpiryRange(snapshot protocol.Snapshot) error

ValidRootSnapshotContainsEntityExpiryRange performs a sanity check to make sure the root snapshot has enough history to encompass at least one full entity expiry window. Entities (in particular transactions and collections) may reference a block within the past `flow.DefaultTransactionExpiry` blocks, so a new node must begin with at least this many blocks worth of history leading up to the snapshot's root block.

Currently, Access Nodes and Consensus Nodes require root snapshots passing this validator function.

  • Consensus Nodes because they process guarantees referencing past blocks
  • Access Nodes because they index transactions referencing past blocks

One of the following conditions must be satisfied to pass this validation:

  1. This is a snapshot build from a first block of spork -> there is no earlier history which transactions/collections could reference
  2. This snapshot sealing segment contains at least one expiry window of blocks -> all possible reference blocks in future transactions/collections will be within the initial history.
  3. This snapshot sealing segment includes the spork root block -> there is no earlier history which transactions/collections could reference

Types

type BootstrapConfig added in v0.22.0 

type BootstrapConfig struct {
	// SkipNetworkAddressValidation flags allows skipping all the network address related
	// validations not needed for an unstaked node
	SkipNetworkAddressValidation bool
}

type BootstrapConfigOptions added in v0.22.0 

type BootstrapConfigOptions func(conf *BootstrapConfig)

type EpochQuery 

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

EpochQuery encapsulates querying epochs w.r.t. a snapshot.

func (*EpochQuery) Current 

func (q *EpochQuery) Current() protocol.Epoch

Current returns the current epoch.

func (*EpochQuery) Next 

func (q *EpochQuery) Next() protocol.Epoch

Next returns the next epoch, if it is available.

func (*EpochQuery) Previous added in v0.13.0 

func (q *EpochQuery) Previous() protocol.Epoch

Previous returns the previous epoch. During the first epoch after the root block, this returns a sentinel error (since there is no previous epoch). For all other epochs, returns the previous epoch.

type FinalizedSnapshot added in v0.31.0 

type FinalizedSnapshot struct {
	Snapshot
	// contains filtered or unexported fields
}

FinalizedSnapshot represents a read-only immutable snapshot of the protocol state at a finalized block. It is guaranteed to have a header available.

func NewFinalizedSnapshot added in v0.31.0 

func NewFinalizedSnapshot(state *State, blockID flow.Identifier, header *flow.Header) *FinalizedSnapshot

NewFinalizedSnapshot instantiates a `FinalizedSnapshot`. CAUTION: the header's ID _must_ match `blockID` (not checked)

func (*FinalizedSnapshot) Head added in v0.31.0 

func (s *FinalizedSnapshot) Head() (*flow.Header, error)

type FollowerState added in v0.14.0 

type FollowerState struct {
	*State
	// contains filtered or unexported fields
}

FollowerState implements a lighter version of a mutable protocol state. When extending the state, it performs hardly any checks on the block payload. Instead, the FollowerState relies on the consensus nodes to run the full payload check and uses quorum certificates to prove validity of block payloads. Consequently, a block B should only be considered valid, if there is a certifying QC for that block QC.View == Block.View && QC.BlockID == Block.ID().

The FollowerState allows non-consensus nodes to execute fork-aware queries against the protocol state, while minimizing the amount of payload checks the non-consensus nodes have to perform.

func NewFollowerState added in v0.14.0 

func NewFollowerState(
	logger zerolog.Logger,
	tracer module.Tracer,
	consumer protocol.Consumer,
	state *State,
	index storage.Index,
	payloads storage.Payloads,
	blockTimer protocol.BlockTimer,
) (*FollowerState, error)

NewFollowerState initializes a light-weight version of a mutable protocol state. This implementation is suitable only for NON-Consensus nodes.

func (*FollowerState) ExtendCertified added in v0.30.0 

func (m *FollowerState) ExtendCertified(ctx context.Context, candidate *flow.Block, certifyingQC *flow.QuorumCertificate) error

ExtendCertified extends the protocol state of a CONSENSUS FOLLOWER. While it checks the validity of the header; it does _not_ check the validity of the payload. Instead, the consensus follower relies on the consensus participants to validate the full payload. Payload validity can be proved by a valid quorum certificate. Certifying QC must match candidate block: 

candidate.View == certifyingQC.View && candidate.ID() == certifyingQC.BlockID

CAUTION:

  • This function expects that `certifyingQC ` has been validated. (otherwise, the state will be corrupted)
  • The parent block must already have been ingested.

Per convention, the protocol state requires that the candidate's parent has already been ingested. Other than that, all valid extensions are accepted. Even if we have enough information to determine that a candidate block is already orphaned (e.g. its view is below the latest finalized view), it is important to accept it nevertheless to avoid spamming vulnerabilities. If a block is orphaned, consensus rules guarantee that there exists only a limited number of descendants which cannot increase anymore. So there is only a finite (generally small) amount of work to do accepting orphaned blocks and all their descendants. However, if we were to drop orphaned blocks, e.g. block X of the orphaned fork X <- Y <- Z, we might not have enough information to reject blocks Y, Z later if we receive them. We would re-request X, then determine it is orphaned and drop it, attempt to ingest Y re-request the unknown parent X and repeat potentially very often.

No errors are expected during normal operations.

func (*FollowerState) Finalize added in v0.14.0 

func (m *FollowerState) Finalize(ctx context.Context, blockID flow.Identifier) error

Finalize marks the specified block as finalized. This method only finalizes one block at a time. Hence, the parent of `blockID` has to be the last finalized block. No errors are expected during normal operations.

type InstanceParams added in v0.33.30 

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

InstanceParams implements the interface protocol.InstanceParams. All functions are served on demand directly from the database, _without_ any caching.

func ReadInstanceParams added in v0.33.30 

func ReadInstanceParams(db *badger.DB, headers storage.Headers, seals storage.Seals) (*InstanceParams, error)

ReadInstanceParams reads the instance parameters from the database and returns them as in-memory representation. No errors are expected during normal operation.

func (*InstanceParams) FinalizedRoot added in v0.33.30 

func (p *InstanceParams) FinalizedRoot() *flow.Header

FinalizedRoot returns the finalized root header of the current protocol state. This will be the head of the protocol state snapshot used to bootstrap this state and may differ from node to node for the same protocol state.

func (*InstanceParams) Seal added in v0.33.30 

func (p *InstanceParams) Seal() *flow.Seal

Seal returns the root block seal of the current protocol state. This is the seal for the `SealedRoot` block that was used to bootstrap this state. It may differ from node to node.

func (*InstanceParams) SealedRoot added in v0.33.30 

func (p *InstanceParams) SealedRoot() *flow.Header

SealedRoot returns the sealed root block. If it's different from FinalizedRoot() block, it means the node is bootstrapped from mid-spork.

type Params 

type Params struct {
	protocol.GlobalParams
	protocol.InstanceParams
}

type ParticipantState added in v0.30.0 

type ParticipantState struct {
	*FollowerState
	// contains filtered or unexported fields
}

ParticipantState implements a mutable state for consensus participant. It can extend the state with a new block, by checking the _entire_ block payload.

func NewFullConsensusState added in v0.14.0 

func NewFullConsensusState(
	logger zerolog.Logger,
	tracer module.Tracer,
	consumer protocol.Consumer,
	state *State,
	index storage.Index,
	payloads storage.Payloads,
	blockTimer protocol.BlockTimer,
	receiptValidator module.ReceiptValidator,
	sealValidator module.SealValidator,
) (*ParticipantState, error)

NewFullConsensusState initializes a new mutable protocol state backed by a badger database. When extending the state with a new block, it checks the _entire_ block payload. Consensus nodes should use the FullConsensusState, while other node roles can use the lighter FollowerState.

func (*ParticipantState) Extend added in v0.30.0 

func (m *ParticipantState) Extend(ctx context.Context, candidate *flow.Block) error

Extend extends the protocol state of a CONSENSUS PARTICIPANT. It checks the validity of the _entire block_ (header and full payload).

CAUTION: per convention, the protocol state requires that the candidate's parent has already been ingested. Otherwise, an exception is returned.

Per convention, the protocol state requires that the candidate's parent has already been ingested. Other than that, all valid extensions are accepted. Even if we have enough information to determine that a candidate block is already orphaned (e.g. its view is below the latest finalized view), it is important to accept it nevertheless to avoid spamming vulnerabilities. If a block is orphaned, consensus rules guarantee that there exists only a limited number of descendants which cannot increase anymore. So there is only a finite (generally small) amount of work to do accepting orphaned blocks and all their descendants. However, if we were to drop orphaned blocks, e.g. block X of the orphaned fork X <- Y <- Z, we might not have enough information to reject blocks Y, Z later if we receive them. We would re-request X, then determine it is orphaned and drop it, attempt to ingest Y re-request the unknown parent X and repeat potentially very often.

Expected errors during normal operations:

  • state.OutdatedExtensionError if the candidate block is outdated (e.g. orphaned)
  • state.InvalidExtensionError if the candidate block is invalid

type Snapshot 

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

Snapshot implements the protocol.Snapshot interface. It represents a read-only immutable snapshot of the protocol state at the block it is constructed with. It allows efficient access to data associated directly with blocks at a given state (finalized, sealed), such as the related header, commit, seed or descending blocks. A block snapshot can lazily convert to an epoch snapshot in order to make data associated directly with epochs accessible through its API.

func (*Snapshot) Commit 

func (s *Snapshot) Commit() (flow.StateCommitment, error)

Commit retrieves the latest execution state commitment at the current block snapshot. This commitment represents the execution state as currently finalized.

func (*Snapshot) Descendants added in v0.17.6 

func (s *Snapshot) Descendants() ([]flow.Identifier, error)

func (*Snapshot) EpochPhase added in v0.37.1 

func (s *Snapshot) EpochPhase() (flow.EpochPhase, error)

func (*Snapshot) EpochProtocolState added in v0.33.30 

func (s *Snapshot) EpochProtocolState() (protocol.EpochProtocolState, error)

EpochProtocolState returns the epoch part of dynamic protocol state that the Head block commits to. The compliance layer guarantees that only valid blocks are appended to the protocol state. Returns state.ErrUnknownSnapshotReference if snapshot reference block is unknown. All other errors should be treated as exceptions. For each block stored there should be a protocol state stored.

func (*Snapshot) Epochs 

func (s *Snapshot) Epochs() protocol.EpochQuery

func (*Snapshot) Head 

func (s *Snapshot) Head() (*flow.Header, error)

func (*Snapshot) Identities 

func (s *Snapshot) Identities(selector flow.IdentityFilter[flow.Identity]) (flow.IdentityList, error)

func (*Snapshot) Identity 

func (s *Snapshot) Identity(nodeID flow.Identifier) (*flow.Identity, error)

func (*Snapshot) Params added in v0.23.2 

func (s *Snapshot) Params() protocol.GlobalParams

func (*Snapshot) ProtocolState added in v0.33.30 

func (s *Snapshot) ProtocolState() (protocol.KVStoreReader, error)

ProtocolState returns the dynamic protocol state that the Head block commits to. The compliance layer guarantees that only valid blocks are appended to the protocol state. Returns state.ErrUnknownSnapshotReference if snapshot reference block is unknown. All other errors should be treated as exceptions. For each block stored there should be a protocol state stored.

func (*Snapshot) QuorumCertificate added in v0.15.0 

func (s *Snapshot) QuorumCertificate() (*flow.QuorumCertificate, error)

QuorumCertificate (QC) returns a valid quorum certificate pointing to the header at this snapshot. The sentinel error storage.ErrNotFound is returned if the QC is unknown.

func (*Snapshot) RandomSource added in v0.25.0 

func (s *Snapshot) RandomSource() ([]byte, error)

RandomSource returns the seed for the current block's snapshot. Expected error returns: * storage.ErrNotFound is returned if the QC is unknown.

func (*Snapshot) SealedResult added in v0.15.0 

func (s *Snapshot) SealedResult() (*flow.ExecutionResult, *flow.Seal, error)

func (*Snapshot) SealingSegment added in v0.15.0 

func (s *Snapshot) SealingSegment() (*flow.SealingSegment, error)

SealingSegment will walk through the chain backward until we reach the block referenced by the latest seal and build a SealingSegment. As we visit each block we check each execution receipt in the block's payload to make sure we have a corresponding execution result, any execution results missing from blocks are stored in the `SealingSegment.ExecutionResults` field. See `model/flow/sealing_segment.md` for detailed technical specification of the Sealing Segment

Expected errors during normal operations:

  • protocol.ErrSealingSegmentBelowRootBlock if sealing segment would stretch beyond the node's local history cut-off
  • protocol.UnfinalizedSealingSegmentError if sealing segment would contain unfinalized blocks (including orphaned blocks)

func (*Snapshot) VersionBeacon added in v0.31.0 

func (s *Snapshot) VersionBeacon() (*flow.SealedVersionBeacon, error)

type State 

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

func Bootstrap added in v0.14.0 

func Bootstrap(
	metrics module.ComplianceMetrics,
	db *badger.DB,
	headers storage.Headers,
	seals storage.Seals,
	results storage.ExecutionResults,
	blocks storage.Blocks,
	qcs storage.QuorumCertificates,
	setups storage.EpochSetups,
	commits storage.EpochCommits,
	epochProtocolStateSnapshots storage.EpochProtocolStateEntries,
	protocolKVStoreSnapshots storage.ProtocolKVStore,
	versionBeacons storage.VersionBeacons,
	root protocol.Snapshot,
	options ...BootstrapConfigOptions,
) (*State, error)

func OpenState added in v0.14.0 

func OpenState(
	metrics module.ComplianceMetrics,
	db *badger.DB,
	headers storage.Headers,
	seals storage.Seals,
	results storage.ExecutionResults,
	blocks storage.Blocks,
	qcs storage.QuorumCertificates,
	setups storage.EpochSetups,
	commits storage.EpochCommits,
	epochProtocolState storage.EpochProtocolStateEntries,
	protocolKVStoreSnapshots storage.ProtocolKVStore,
	versionBeacons storage.VersionBeacons,
) (*State, error)

func (*State) AtBlockID 

func (state *State) AtBlockID(blockID flow.Identifier) protocol.Snapshot

AtBlockID returns a snapshot for the block with the given ID. The block may be finalized or un-finalized. This function may return an invalid.Snapshot with:

  • state.ErrUnknownSnapshotReference: -> if no block with the given ID exists in the state
  • exception for critical unexpected storage errors

func (*State) AtHeight 

func (state *State) AtHeight(height uint64) protocol.Snapshot

AtHeight returns a snapshot for the finalized block at the given height. This function may return an invalid.Snapshot with:

  • state.ErrUnknownSnapshotReference: -> if no block with the given height has been finalized, even if it is incorporated -> if the given height is below the root height
  • exception for critical unexpected storage errors

func (*State) Final 

func (state *State) Final() protocol.Snapshot

Final returns a snapshot for the latest finalized block. A latest finalized block must always exist, so this function always returns a valid snapshot.

func (*State) Params 

func (state *State) Params() protocol.Params

func (*State) Sealed 

func (state *State) Sealed() protocol.Snapshot

Sealed returns a snapshot for the latest sealed block. A latest sealed block must always exist, so this function always returns a valid snapshot.

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.