kv

package
v4.2.0-rc.0 Latest Latest
Warning

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

 Go to latest Published: Jan 8, 2024 License: GPL-3.0 Imports: 47 Imported by: 23

Documentation

Overview

Package kv defines a bolt-db, key-value store implementation of the Database interface defined by a Prysm beacon node.

Index

Constants

View Source 
const (
	// NumOfValidatorEntries is the size of the validator cache entries.
	// we expect to hold a max of 200K validators, so setting it to 2 million (10x the capacity).
	NumOfValidatorEntries = 1 << 21
	// ValidatorEntryMaxCost is set to ~64Mb to allow 200K validators entries to be cached.
	ValidatorEntryMaxCost = 1 << 26
	// BeaconNodeDbDirName is the name of the directory containing the beacon node database.
	BeaconNodeDbDirName = "beaconchaindata"
	// DatabaseFileName is the name of the beacon node database.
	DatabaseFileName = "beaconchain.db"
)

Variables

View Source 
var BlockCacheSize = int64(1 << 21)

BlockCacheSize specifies 1000 slots worth of blocks cached, which would be approximately 2MB

View Source 
var Buckets = [][]byte{
	attestationsBucket,
	blocksBucket,
	stateBucket,
	proposerSlashingsBucket,
	attesterSlashingsBucket,
	voluntaryExitsBucket,
	chainMetadataBucket,
	checkpointBucket,
	powchainBucket,
	stateSummaryBucket,
	stateValidatorsBucket,

	attestationHeadBlockRootBucket,
	attestationSourceRootIndicesBucket,
	attestationSourceEpochIndicesBucket,
	attestationTargetRootIndicesBucket,
	attestationTargetEpochIndicesBucket,
	blockSlotIndicesBucket,
	stateSlotIndicesBucket,
	blockParentRootIndicesBucket,
	finalizedBlockRootsIndexBucket,
	blockRootValidatorHashesBucket,

	newStateServiceCompatibleBucket,

	migrationsBucket,

	feeRecipientBucket,
	registrationBucket,

	blobsBucket,
}
View Source 
var ErrDeleteJustifiedAndFinalized = errors.New("cannot delete finalized block or state")

ErrDeleteJustifiedAndFinalized is raised when we attempt to delete a finalized block/state

View Source 
var ErrNotFound = errors.New("not found in db")

ErrNotFound can be used directly, or as a wrapped DBError, whenever a db method needs to indicate that a value couldn't be found.

View Source 
var ErrNotFoundBackfillBlockRoot = errors.Wrap(ErrNotFound, "BackfillBlockRoot")

ErrNotFoundBackfillBlockRoot is an error specifically for the origin block root getter

View Source 
var ErrNotFoundFeeRecipient = errors.Wrap(ErrNotFound, "fee recipient")

ErrNotFoundFeeRecipient is a not found error specifically for the fee recipient getter

View Source 
var ErrNotFoundGenesisBlockRoot = errors.Wrap(ErrNotFound, "OriginGenesisRoot")

ErrNotFoundGenesisBlockRoot means no genesis block root was found, indicating the db was not initialized with genesis

View Source 
var ErrNotFoundOriginBlockRoot = errors.Wrap(ErrNotFound, "OriginBlockRoot")

ErrNotFoundOriginBlockRoot is an error specifically for the origin block root getter

View Source 
var ErrNotFoundState = errors.Wrap(ErrNotFound, "state not found")

Functions

func StoreDatafilePath added in v4.2.0 

func StoreDatafilePath(dirPath string) string

StoreDatafilePath is the canonical construction of a full database file path from the directory path, so that code outside this package can find the full path in a consistent way.

Types

type KVStoreOption added in v4.2.0 

type KVStoreOption func(*Store)

KVStoreOption is a functional option that modifies a kv.Store.

func WithBlobRetentionEpochs 

func WithBlobRetentionEpochs(e primitives.Epoch) KVStoreOption

WithBlobRetentionEpochs sets the variable configuring the blob retention window.

type Store 

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

Store defines an implementation of the Prysm Database interface using BoltDB as the underlying persistent kv-store for Ethereum Beacon Nodes.

func NewKVStore 

func NewKVStore(ctx context.Context, dirPath string, opts ...KVStoreOption) (*Store, error)

NewKVStore initializes a new boltDB key-value store at the directory path specified, creates the kv-buckets based on the schema, and stores an open connection db object as a property of the Store struct.

func (*Store) ArchivedPointRoot 

func (s *Store) ArchivedPointRoot(ctx context.Context, slot primitives.Slot) [32]byte

ArchivedPointRoot returns the block root of an archived point from the DB. This is essential for cold state management and to restore a cold state.

func (*Store) BackfillBlockRoot 

func (s *Store) BackfillBlockRoot(ctx context.Context) ([32]byte, error)

BackfillBlockRoot keeps track of the highest block available before the OriginCheckpointBlockRoot

func (*Store) Backup 

func (s *Store) Backup(ctx context.Context, outputDir string, permissionOverride bool) error

Backup the database to the datadir backup directory. Example for backup at slot 345: $DATADIR/backups/prysm_beacondb_at_slot_0000345.backup

func (*Store) BlobSidecarsByRoot added in v4.1.0 

func (s *Store) BlobSidecarsByRoot(ctx context.Context, root [32]byte, indices ...uint64) ([]*ethpb.DeprecatedBlobSidecar, error)

BlobSidecarsByRoot retrieves the blobs for the given beacon block root. If the `indices` argument is omitted, all blobs for the root will be returned. Otherwise, the result will be filtered to only include the specified indices. An error will result if an invalid index is specified. The bucket size is bounded by 131072 entries. That's the most blobs a node will keep before rotating it out.

func (*Store) BlobSidecarsBySlot added in v4.1.0 

func (s *Store) BlobSidecarsBySlot(ctx context.Context, slot types.Slot, indices ...uint64) ([]*ethpb.DeprecatedBlobSidecar, error)

BlobSidecarsBySlot retrieves BlobSidecars for the given slot. If the `indices` argument is omitted, all blobs for the slot will be returned. Otherwise, the result will be filtered to only include the specified indices. An error will result if an invalid index is specified. The bucket size is bounded by 131072 entries. That's the most blobs a node will keep before rotating it out.

func (*Store) Block 

func (s *Store) Block(ctx context.Context, blockRoot [32]byte) (interfaces.ReadOnlySignedBeaconBlock, error)

Block retrieval by root.

func (*Store) BlockRoots 

func (s *Store) BlockRoots(ctx context.Context, f *filters.QueryFilter) ([][32]byte, error)

BlockRoots retrieves a list of beacon block roots by filter criteria. If the caller requires both the blocks and the block roots for a certain filter they should instead use the Blocks function rather than use BlockRoots. During periods of non finality there are potential race conditions which leads to differing roots when calling the db multiple times for the same filter.

func (*Store) BlockRootsBySlot 

func (s *Store) BlockRootsBySlot(ctx context.Context, slot primitives.Slot) (bool, [][32]byte, error)

BlockRootsBySlot retrieves a list of beacon block roots by slot

func (*Store) Blocks 

func (s *Store) Blocks(ctx context.Context, f *filters.QueryFilter) ([]interfaces.ReadOnlySignedBeaconBlock, [][32]byte, error)

Blocks retrieves a list of beacon blocks and its respective roots by filter criteria.

func (*Store) BlocksBySlot 

func (s *Store) BlocksBySlot(ctx context.Context, slot primitives.Slot) ([]interfaces.ReadOnlySignedBeaconBlock, error)

BlocksBySlot retrieves a list of beacon blocks and its respective roots by slot.

func (*Store) CleanUpDirtyStates 

func (s *Store) CleanUpDirtyStates(ctx context.Context, slotsPerArchivedPoint primitives.Slot) error

CleanUpDirtyStates removes states in DB that falls to under archived point interval rules. Only following states would be kept: 1.) state_slot % archived_interval == 0. (e.g. archived_interval=2048, states with slot 2048, 4096... etc) 2.) archived_interval - archived_interval/3 < state_slot % archived_interval 

(e.g. archived_interval=2048, states with slots after 1365).
This is to tolerate skip slots. Not every state lays on the boundary.

3.) state with current finalized root 4.) unfinalized States

func (*Store) ClearDB 

func (s *Store) ClearDB() error

ClearDB removes the previously stored database in the data directory.

func (*Store) Close 

func (s *Store) Close() error

Close closes the underlying BoltDB database.

func (*Store) DatabasePath 

func (s *Store) DatabasePath() string

DatabasePath at which this database writes files.

func (*Store) DeleteBlobSidecars 

func (s *Store) DeleteBlobSidecars(ctx context.Context, beaconBlockRoot [32]byte) error

DeleteBlobSidecars returns true if the blobs are in the db.

func (*Store) DeleteBlock 

func (s *Store) DeleteBlock(ctx context.Context, root [32]byte) error

DeleteBlock from the db This deletes the root entry from all buckets in the blocks DB If the block is finalized this function returns an error

func (*Store) DeleteState 

func (s *Store) DeleteState(ctx context.Context, blockRoot [32]byte) error

DeleteState by block root.

func (*Store) DeleteStates 

func (s *Store) DeleteStates(ctx context.Context, blockRoots [][32]byte) error

DeleteStates by block roots.

func (*Store) DepositContractAddress 

func (s *Store) DepositContractAddress(ctx context.Context) ([]byte, error)

DepositContractAddress returns contract address is the address of the deposit contract on the proof of work chain.

func (*Store) EnsureEmbeddedGenesis 

func (s *Store) EnsureEmbeddedGenesis(ctx context.Context) error

EnsureEmbeddedGenesis checks that a genesis block has been generated when an embedded genesis state is used. If a genesis block does not exist, but a genesis state does, then we should call SaveGenesisData on the existing genesis state.

func (*Store) ExecutionChainData 

func (s *Store) ExecutionChainData(ctx context.Context) (*v2.ETH1ChainData, error)

ExecutionChainData retrieves the execution chain data.

func (*Store) FeeRecipientByValidatorID 

func (s *Store) FeeRecipientByValidatorID(ctx context.Context, id primitives.ValidatorIndex) (common.Address, error)

FeeRecipientByValidatorID returns the fee recipient for a validator id. `ErrNotFoundFeeRecipient` is returned if the validator id is not found.

func (*Store) FinalizedCheckpoint 

func (s *Store) FinalizedCheckpoint(ctx context.Context) (*ethpb.Checkpoint, error)

FinalizedCheckpoint returns the latest finalized checkpoint in beacon chain.

func (*Store) FinalizedChildBlock 

func (s *Store) FinalizedChildBlock(ctx context.Context, blockRoot [32]byte) (interfaces.ReadOnlySignedBeaconBlock, error)

FinalizedChildBlock returns the child block of a provided finalized block. If no finalized block or its respective child block exists we return with a nil block.

func (*Store) GenesisBlock 

func (s *Store) GenesisBlock(ctx context.Context) (interfaces.ReadOnlySignedBeaconBlock, error)

GenesisBlock retrieves the genesis block of the beacon chain.

func (*Store) GenesisBlockRoot 

func (s *Store) GenesisBlockRoot(ctx context.Context) ([32]byte, error)

func (*Store) GenesisState 

func (s *Store) GenesisState(ctx context.Context) (state.BeaconState, error)

GenesisState returns the genesis state in beacon chain.

func (*Store) HasArchivedPoint 

func (s *Store) HasArchivedPoint(ctx context.Context, slot primitives.Slot) bool

HasArchivedPoint returns true if an archived point exists in DB.

func (*Store) HasBlock 

func (s *Store) HasBlock(ctx context.Context, blockRoot [32]byte) bool

HasBlock checks if a block by root exists in the db.

func (*Store) HasState 

func (s *Store) HasState(ctx context.Context, blockRoot [32]byte) bool

HasState checks if a state by root exists in the db.

func (*Store) HasStateSummary 

func (s *Store) HasStateSummary(ctx context.Context, blockRoot [32]byte) bool

HasStateSummary returns true if a state summary exists in DB.

func (*Store) HeadBlock 

func (s *Store) HeadBlock(ctx context.Context) (interfaces.ReadOnlySignedBeaconBlock, error)

HeadBlock returns the latest canonical block in the Ethereum Beacon Chain.

func (*Store) HighestRootsBelowSlot 

func (s *Store) HighestRootsBelowSlot(ctx context.Context, slot primitives.Slot) (fs primitives.Slot, roots [][32]byte, err error)

HighestRootsBelowSlot returns roots from the database slot index from the highest slot below the input slot. The slot value at the beginning of the return list is the slot where the roots were found. This is helpful so that calling code can make decisions based on the slot without resolving the blocks to discover their slot (for instance checking which root is canonical in fork choice, which operates purely on roots, then if no canonical block is found, continuing to search through lower slots).

func (*Store) HighestSlotStatesBelow 

func (s *Store) HighestSlotStatesBelow(ctx context.Context, slot primitives.Slot) ([]state.ReadOnlyBeaconState, error)

HighestSlotStatesBelow returns the states with the highest slot below the input slot from the db. Ideally there should just be one state per slot, but given validator can double propose, a single slot could have multiple block roots and results states. This returns a list of states.

func (*Store) IsFinalizedBlock 

func (s *Store) IsFinalizedBlock(ctx context.Context, blockRoot [32]byte) bool

IsFinalizedBlock returns true if the block root is present in the finalized block root index. A beacon block root contained exists in this index if it is considered finalized and canonical. Note: beacon blocks from the latest finalized epoch return true, whether or not they are considered canonical in the "head view" of the beacon node.

func (*Store) JustifiedCheckpoint 

func (s *Store) JustifiedCheckpoint(ctx context.Context) (*ethpb.Checkpoint, error)

JustifiedCheckpoint returns the latest justified checkpoint in beacon chain.

func (*Store) LastArchivedRoot 

func (s *Store) LastArchivedRoot(ctx context.Context) [32]byte

LastArchivedRoot from the db.

func (*Store) LastArchivedSlot 

func (s *Store) LastArchivedSlot(ctx context.Context) (primitives.Slot, error)

LastArchivedSlot from the db.

func (*Store) LastValidatedCheckpoint 

func (s *Store) LastValidatedCheckpoint(ctx context.Context) (*ethpb.Checkpoint, error)

LastValidatedCheckpoint returns the latest fully validated checkpoint in beacon chain.

func (*Store) LoadGenesis 

func (s *Store) LoadGenesis(ctx context.Context, sb []byte) error

LoadGenesis loads a genesis state from a ssz-serialized byte slice, if no genesis exists already.

func (*Store) OriginCheckpointBlockRoot 

func (s *Store) OriginCheckpointBlockRoot(ctx context.Context) ([32]byte, error)

OriginCheckpointBlockRoot returns the value written to the db in SaveOriginCheckpointBlockRoot This is the root of a finalized block within the weak subjectivity period at the time the chain was started, used to initialize the database and chain without syncing from genesis.

func (*Store) RegistrationByValidatorID 

func (s *Store) RegistrationByValidatorID(ctx context.Context, id primitives.ValidatorIndex) (*ethpb.ValidatorRegistrationV1, error)

RegistrationByValidatorID returns the validator registration object for a validator id. `ErrNotFoundFeeRecipient` is returned if the validator id is not found.

func (*Store) RunMigrations 

func (s *Store) RunMigrations(ctx context.Context) error

RunMigrations defined in the migrations array.

func (*Store) SaveBackfillBlockRoot 

func (s *Store) SaveBackfillBlockRoot(ctx context.Context, blockRoot [32]byte) error

SaveBackfillBlockRoot is used to keep track of the most recently backfilled block root when the node was initialized via checkpoint sync.

func (*Store) SaveBlobSidecar added in v4.1.0 

func (s *Store) SaveBlobSidecar(ctx context.Context, scs []*ethpb.DeprecatedBlobSidecar) error

SaveBlobSidecar saves the blobs for a given epoch in the sidecar bucket. When we receive a blob:

  1. Convert slot using a modulo operator to [0, maxSlots] where maxSlots = MAX_EPOCHS_TO_PERSIST_BLOBS*SLOTS_PER_EPOCH

  2. Compute key for blob as bytes(slot_to_rotating_buffer(blob.slot)) ++ bytes(blob.slot) ++ blob.block_root

  3. Begin the save algorithm: If the incoming blob has a slot bigger than the saved slot at the spot in the rotating keys buffer, we overwrite all elements for that slot. Otherwise, we merge the blob with an existing one. Trying to replace a newer blob with an older one is an error.

func (*Store) SaveBlock 

func (s *Store) SaveBlock(ctx context.Context, signed interfaces.ReadOnlySignedBeaconBlock) error

SaveBlock to the db.

func (*Store) SaveBlocks 

func (s *Store) SaveBlocks(ctx context.Context, blks []interfaces.ReadOnlySignedBeaconBlock) error

SaveBlocks via bulk updates to the db.

func (*Store) SaveDepositContractAddress 

func (s *Store) SaveDepositContractAddress(ctx context.Context, addr common.Address) error

SaveDepositContractAddress to the db. It returns an error if an address has been previously saved.

func (*Store) SaveExecutionChainData 

func (s *Store) SaveExecutionChainData(ctx context.Context, data *v2.ETH1ChainData) error

SaveExecutionChainData saves the execution chain data.

func (*Store) SaveFeeRecipientsByValidatorIDs 

func (s *Store) SaveFeeRecipientsByValidatorIDs(ctx context.Context, ids []primitives.ValidatorIndex, feeRecipients []common.Address) error

SaveFeeRecipientsByValidatorIDs saves the fee recipients for validator ids. Error is returned if `ids` and `recipients` are not the same length.

func (*Store) SaveFinalizedCheckpoint 

func (s *Store) SaveFinalizedCheckpoint(ctx context.Context, checkpoint *ethpb.Checkpoint) error

SaveFinalizedCheckpoint saves finalized checkpoint in beacon chain.

func (*Store) SaveGenesisBlockRoot 

func (s *Store) SaveGenesisBlockRoot(ctx context.Context, blockRoot [32]byte) error

SaveGenesisBlockRoot to the db.

func (*Store) SaveGenesisData 

func (s *Store) SaveGenesisData(ctx context.Context, genesisState state.BeaconState) error

SaveGenesisData bootstraps the beaconDB with a given genesis state.

func (*Store) SaveHeadBlockRoot 

func (s *Store) SaveHeadBlockRoot(ctx context.Context, blockRoot [32]byte) error

SaveHeadBlockRoot to the db.

func (*Store) SaveJustifiedCheckpoint 

func (s *Store) SaveJustifiedCheckpoint(ctx context.Context, checkpoint *ethpb.Checkpoint) error

SaveJustifiedCheckpoint saves justified checkpoint in beacon chain.

func (*Store) SaveLastValidatedCheckpoint 

func (s *Store) SaveLastValidatedCheckpoint(ctx context.Context, checkpoint *ethpb.Checkpoint) error

SaveLastValidatedCheckpoint saves the last validated checkpoint in beacon chain.

func (*Store) SaveOrigin 

func (s *Store) SaveOrigin(ctx context.Context, serState, serBlock []byte) error

SaveOrigin loads an ssz serialized Block & BeaconState from an io.Reader (ex: an open file) prepares the database so that the beacon node can begin syncing, using the provided values as their point of origin. This is an alternative to syncing from genesis, and should only be run on an empty database.

func (*Store) SaveOriginCheckpointBlockRoot 

func (s *Store) SaveOriginCheckpointBlockRoot(ctx context.Context, blockRoot [32]byte) error

SaveOriginCheckpointBlockRoot is used to keep track of the block root used for syncing from a checkpoint origin. This should be a finalized block from within the current weak subjectivity period. This value is used by a running beacon chain node to locate the state at the beginning of the chain history, in places where genesis would typically be used.

func (*Store) SaveRegistrationsByValidatorIDs 

func (s *Store) SaveRegistrationsByValidatorIDs(ctx context.Context, ids []primitives.ValidatorIndex, regs []*ethpb.ValidatorRegistrationV1) error

SaveRegistrationsByValidatorIDs saves the validator registrations for validator ids. Error is returned if `ids` and `registrations` are not the same length.

func (*Store) SaveState 

func (s *Store) SaveState(ctx context.Context, st state.ReadOnlyBeaconState, blockRoot [32]byte) error

SaveState stores a state to the db using block's signing root which was used to generate the state.

func (*Store) SaveStateSummaries 

func (s *Store) SaveStateSummaries(ctx context.Context, summaries []*ethpb.StateSummary) error

SaveStateSummaries saves state summary objects to the DB.

func (*Store) SaveStateSummary 

func (s *Store) SaveStateSummary(ctx context.Context, summary *ethpb.StateSummary) error

SaveStateSummary saves a state summary object to the DB.

func (*Store) SaveStates 

func (s *Store) SaveStates(ctx context.Context, states []state.ReadOnlyBeaconState, blockRoots [][32]byte) error

SaveStates stores multiple states to the db using the provided corresponding roots.

func (*Store) SaveStatesEfficient 

func (s *Store) SaveStatesEfficient(ctx context.Context, states []state.ReadOnlyBeaconState, blockRoots [][32]byte) error

SaveStatesEfficient stores multiple states to the db (new schema) using the provided corresponding roots.

func (*Store) State 

func (s *Store) State(ctx context.Context, blockRoot [32]byte) (state.BeaconState, error)

State returns the saved state using block's signing root, this particular block was used to generate the state.

func (*Store) StateOrError 

func (s *Store) StateOrError(ctx context.Context, blockRoot [32]byte) (state.BeaconState, error)

StateOrError is just like State(), except it only returns a non-error response if the requested state is found in the database.

func (*Store) StateSummary 

func (s *Store) StateSummary(ctx context.Context, blockRoot [32]byte) (*ethpb.StateSummary, error)

StateSummary returns the state summary object from the db using input block root.

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.