pebble

package
v1.24.4 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2026 License: GPL-3.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	BlockTypeHeader  uint16 = 1
	BlockTypeBody    uint16 = 2
	BlockTypePayload uint16 = 3
	BlockTypeBal     uint16 = 4
)
View Source 
const (
	// Duties key record types (stored at byte offset 10).
	DutiesRecordMeta       uint8 = 0 // per-epoch header
	DutiesRecordCommittees uint8 = 1 // per-slot attester committees
	DutiesRecordPtc        uint8 = 2 // per-slot PTC members

	// DutiesKeyLen: [ns:2][firstSlot:8][type:1][slotIndex:2] = 13 bytes
	DutiesKeyLen = 2 + 8 + 1 + 2

	// DivergingDutiesKeyLen: [ns:2][firstSlot:8][depRoot:32][type:1][slotIndex:2]
	// = 45 bytes. Shares the duties namespace with canonical keys but is length-
	// distinct (45 vs 13), so prune range-deletes both while the epoch-count scan
	// only tallies canonical meta keys.
	DivergingDutiesKeyLen = 2 + 8 + 32 + 1 + 2
)

Per-epoch duties (KeyNamespaceDuties, see pebble.go) are stored as several keys (one meta key plus one key per slot for committees and PTC) so a single slot can be read with a point lookup without loading the whole epoch. Keys are grouped by the epoch's first slot to allow efficient range deletion.

View Source 
const (
	KeyNamespaceBlock       uint16 = 1 // block components: [ns1][root][blockType]
	KeyNamespaceExecData    uint16 = 2 // execution data (DXTX blobs): [ns2][slot][hash4]
	KeyNamespaceLRU         uint16 = 2 // block-component LRU records: [ns2][root]
	KeyNamespaceDuties      uint16 = 3 // per-epoch duties: [ns3][firstSlot][type][slotIdx]
	KeyNamespaceTxHash      uint16 = 4 // tx-hash index lookup: [ns4][prefix10][tx_uid8]
	KeyNamespaceTxHashPrune uint16 = 5 // tx-hash index prune-order: [ns5][tx_uid8]
	KeyNamespaceAccessTrack uint16 = 6 // exec/duties access records: [ns6][entityNs][slot][tail]
	KeyNamespaceBids        uint16 = 7 // per-slot bids objects: [ns7][slot]
)

Key namespaces. Every Pebble key begins with a 2-byte big-endian namespace prefix. Namespace 2 is shared by exec-data objects and the block-component LRU records; they never collide because their keys differ in length.

View Source 
const (
	// BidsKeyLen: [ns:2][slot:8] = 10 bytes
	BidsKeyLen = 2 + 8
)

Per-slot bids objects (KeyNamespaceBids, see pebble.go) are stored as a single key per slot holding the encoded BIDS object.

Variables

This section is empty.

Functions

func MakeBidsKey added in v1.24.4 

func MakeBidsKey(slot uint64) []byte

MakeBidsKey builds a Pebble key for a per-slot bids object. Exported so tooling (e.g. the blockdb-copy utility) can read/write bids objects directly.

func MakeDivergingDutiesKey added in v1.24.4 

func MakeDivergingDutiesKey(firstSlot uint64, depRoot [32]byte, recordType uint8, slotIndex uint16) []byte

MakeDivergingDutiesKey builds a Pebble key for a diverging-fork duties record, keyed additionally by the fork's dependent root.

func MakeDutiesKey added in v1.24.0 

func MakeDutiesKey(firstSlot uint64, recordType uint8, slotIndex uint16) []byte

MakeDutiesKey builds a Pebble key for a duties record. Exported so tooling (e.g. the blockdb-copy utility) can read/write duties records directly.

func NewPebbleEngine 

func NewPebbleEngine(config dtypes.PebbleBlockDBConfig) (types.BlockDbEngine, error)

Types

type CacheCleanup added in v1.21.0 

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

CacheCleanup manages background cleanup of cached data.

func NewCacheCleanup added in v1.21.0 

func NewCacheCleanup(engine *PebbleEngine, logger logrus.FieldLogger, cacheMode bool) *CacheCleanup

NewCacheCleanup creates a new cleanup manager. cacheMode selects tiered (cache eviction) vs pebble (authoritative deletion) semantics; see runCleanup.

func (*CacheCleanup) DeleteLRU added in v1.21.0 

func (c *CacheCleanup) DeleteLRU(root []byte)

DeleteLRU removes LRU data for a block (call when deleting block data).

func (*CacheCleanup) FlushLRU added in v1.21.0 

func (c *CacheCleanup) FlushLRU()

FlushLRU flushes buffered LRU updates to Pebble.

func (*CacheCleanup) RecordAccess added in v1.21.0 

func (c *CacheCleanup) RecordAccess(root []byte, flags types.BlockDataFlags)

RecordAccess records an access for LRU tracking. Buffered until flush.

func (*CacheCleanup) RecordDutiesAccess added in v1.24.1 

func (c *CacheCleanup) RecordDutiesAccess(firstSlot uint64)

RecordDutiesAccess buffers a last-access update for an epoch's duties. No-op unless duties eviction is in LRU mode.

func (*CacheCleanup) RecordExecAccess added in v1.24.1 

func (c *CacheCleanup) RecordExecAccess(slot uint64, blockHash []byte)

RecordExecAccess buffers a last-access update for an exec-data object. No-op unless exec-data eviction is in LRU mode.

func (*CacheCleanup) SetTimeToSlotFn added in v1.24.1 

func (c *CacheCleanup) SetTimeToSlotFn(fn func(t time.Time) uint64)

SetTimeToSlotFn installs the time->slot resolver used by age-based eviction of the slot-keyed namespaces. Safe to call once after construction, before the cleanup loop needs it.

func (*CacheCleanup) Start added in v1.21.0 

func (c *CacheCleanup) Start()

Start begins the background cleanup loop.

func (*CacheCleanup) Stop added in v1.21.0 

func (c *CacheCleanup) Stop()

Stop stops the background cleanup loop.

type PebbleEngine 

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

func (*PebbleEngine) AddBlock 

func (e *PebbleEngine) AddBlock(
	_ context.Context,
	_ uint64,
	root []byte,
	dataCb func() (*types.BlockData, error),
) (bool, bool, error)

AddBlock stores block data. Returns (added, updated, error). - added: true if a new block was created - updated: true if an existing block was updated with new components

func (*PebbleEngine) AddDivergingEpochDuties added in v1.24.4 

func (e *PebbleEngine) AddDivergingEpochDuties(_ context.Context, duties *types.EpochDuties) (int64, error)

AddDivergingEpochDuties stores the duties of a diverging fork, keyed by its dependent root alongside the epoch's first slot.

func (*PebbleEngine) AddEpochDuties added in v1.24.0 

func (e *PebbleEngine) AddEpochDuties(_ context.Context, duties *types.EpochDuties) (int64, error)

AddEpochDuties stores the duties for an epoch as per-slot keys.

func (*PebbleEngine) AddExecData added in v1.20.3 

func (e *PebbleEngine) AddExecData(_ context.Context, slot uint64, blockHash []byte, data []byte) (int64, error)

AddExecData stores execution data for a block as a full DXTX blob. Returns the stored size in bytes.

func (*PebbleEngine) AddSlotBids added in v1.24.4 

func (e *PebbleEngine) AddSlotBids(_ context.Context, bids *types.SlotBids) (int64, error)

AddSlotBids stores the encoded bids object for a slot.

func (*PebbleEngine) Close 

func (e *PebbleEngine) Close() error

func (*PebbleEngine) DeleteExecData added in v1.20.3 

func (e *PebbleEngine) DeleteExecData(_ context.Context, slot uint64, blockHash []byte) error

DeleteExecData deletes execution data for a specific block.

func (*PebbleEngine) EstimateTxHashIndexSize added in v1.24.1 

func (e *PebbleEngine) EstimateTxHashIndexSize() int64

EstimateTxHashIndexSize returns the approximate on-disk bytes used by the tx-hash index, covering both the lookup (ns4) and prune-order (ns5) namespaces that together make up the index.

func (*PebbleEngine) GetBlock 

func (e *PebbleEngine) GetBlock(
	_ context.Context,
	_ uint64,
	root []byte,
	flags types.BlockDataFlags,
	parseBlock func(uint64, []byte) (any, error),
	parsePayload func(uint64, []byte) (any, error),
) (*types.BlockData, error)

GetBlock retrieves block data with selective loading based on flags. Note: LRU access tracking should be done by the caller via CacheCleanup.RecordAccess() to avoid expensive read-modify-write operations on every access.

func (*PebbleEngine) GetConfig added in v1.21.0 

func (e *PebbleEngine) GetConfig() dtypes.PebbleBlockDBConfig

GetConfig returns the engine configuration.

func (*PebbleEngine) GetDB added in v1.20.4 

func (e *PebbleEngine) GetDB() *pebble.DB

GetDB returns the underlying pebble database for metrics collection.

func (*PebbleEngine) GetEpochDuties added in v1.24.0 

func (e *PebbleEngine) GetEpochDuties(_ context.Context, firstSlot uint64) (*types.EpochDuties, error)

GetEpochDuties reads and reassembles the full duties for an epoch.

func (*PebbleEngine) GetEpochDutiesForRoot added in v1.24.4 

func (e *PebbleEngine) GetEpochDutiesForRoot(_ context.Context, firstSlot uint64, depRoot [32]byte) (*types.EpochDuties, error)

GetEpochDutiesForRoot reads and reassembles the diverging-fork duties for an epoch under the given dependent root. Returns nil, nil if not found.

func (*PebbleEngine) GetExecData added in v1.20.3 

func (e *PebbleEngine) GetExecData(_ context.Context, slot uint64, blockHash []byte) ([]byte, error)

GetExecData retrieves the full DXTX blob for a block. Returns nil, nil if not found.

func (*PebbleEngine) GetExecDataRange added in v1.20.3 

func (e *PebbleEngine) GetExecDataRange(_ context.Context, slot uint64, blockHash []byte, offset int64, length int64) ([]byte, error)

GetExecDataRange retrieves a byte range of the DXTX blob.

func (*PebbleEngine) GetExecDataTxSections added in v1.20.3 

func (e *PebbleEngine) GetExecDataTxSections(_ context.Context, slot uint64, blockHash []byte, txHash []byte, sections uint32) (*types.ExecDataTxSections, error)

GetExecDataTxSections retrieves compressed section data for a single transaction by loading the full DXTX blob and extracting the requested sections from it.

func (*PebbleEngine) GetObjectStats added in v1.24.4 

func (e *PebbleEngine) GetObjectStats(_ context.Context) (*types.BlockDbObjectStats, error)

GetObjectStats scans the key namespaces to count stored objects: blocks (ns1, header records; includes orphaned blocks), canonical vs diverging duties (ns3), and per-slot bids (ns7). The scans are key-only (no value reads except bids sizing) so they stay cheap enough for the debug page.

func (*PebbleEngine) GetSlotBids added in v1.24.4 

func (e *PebbleEngine) GetSlotBids(_ context.Context, slot uint64) (*types.SlotBids, error)

GetSlotBids reads and decodes the bids object for a slot.

func (*PebbleEngine) GetSlotCommittees added in v1.24.0 

func (e *PebbleEngine) GetSlotCommittees(_ context.Context, firstSlot uint64, slot uint64) ([][]uint64, error)

GetSlotCommittees reads the attester committees for a single slot.

func (*PebbleEngine) GetSlotCommitteesForRoot added in v1.24.4 

func (e *PebbleEngine) GetSlotCommitteesForRoot(_ context.Context, firstSlot uint64, slot uint64, depRoot [32]byte) ([][]uint64, error)

GetSlotCommitteesForRoot reads the attester committees for a single slot of a diverging fork identified by depRoot.

func (*PebbleEngine) GetSlotPtc added in v1.24.0 

func (e *PebbleEngine) GetSlotPtc(_ context.Context, firstSlot uint64, slot uint64) ([]uint64, error)

GetSlotPtc reads the PTC members for a single slot.

func (*PebbleEngine) GetSlotPtcForRoot added in v1.24.4 

func (e *PebbleEngine) GetSlotPtcForRoot(_ context.Context, firstSlot uint64, slot uint64, depRoot [32]byte) ([]uint64, error)

GetSlotPtcForRoot reads the PTC members for a single slot of a diverging fork.

func (*PebbleEngine) GetStoredComponents added in v1.21.0 

func (e *PebbleEngine) GetStoredComponents(_ context.Context, _ uint64, root []byte) (types.BlockDataFlags, error)

GetStoredComponents returns which components exist for a block.

func (*PebbleEngine) HasEpochDuties added in v1.24.0 

func (e *PebbleEngine) HasEpochDuties(_ context.Context, firstSlot uint64) (bool, error)

HasEpochDuties checks if duties exist for an epoch (via its meta key).

func (*PebbleEngine) HasExecData added in v1.20.3 

func (e *PebbleEngine) HasExecData(_ context.Context, slot uint64, blockHash []byte) (bool, error)

HasExecData checks if execution data exists for a block.

func (*PebbleEngine) LookupTxHash added in v1.24.1 

func (e *PebbleEngine) LookupTxHash(_ context.Context, prefix []byte) ([]uint64, error)

LookupTxHash returns candidate tx_uids for an exact prefix.

func (*PebbleEngine) LookupTxHashRange added in v1.24.1 

func (e *PebbleEngine) LookupTxHashRange(_ context.Context, lo, hi []byte) ([]uint64, error)

LookupTxHashRange returns candidate tx_uids for prefixes in [lo, hi), capped.

func (*PebbleEngine) PruneEpochDutiesBefore added in v1.24.0 

func (e *PebbleEngine) PruneEpochDutiesBefore(_ context.Context, maxFirstSlot uint64) (int64, error)

PruneEpochDutiesBefore deletes all duties records for epochs whose first slot is before maxFirstSlot. Returns the number of epochs deleted. The DeleteRange spans the whole duties namespace up to maxFirstSlot, so diverging-fork keys (which share the namespace and sort by their firstSlot prefix) are removed together with the canonical keys; the epoch counter only tallies canonical meta keys (length-distinct at DutiesKeyLen).

func (*PebbleEngine) PruneExecDataBefore added in v1.20.3 

func (e *PebbleEngine) PruneExecDataBefore(_ context.Context, maxSlot uint64) (int64, error)

PruneExecDataBefore deletes execution data for all slots before maxSlot. Returns the number of objects deleted.

func (*PebbleEngine) PruneSlotBidsBefore added in v1.24.4 

func (e *PebbleEngine) PruneSlotBidsBefore(_ context.Context, maxSlot uint64) (int64, error)

PruneSlotBidsBefore deletes all bids objects for slots before maxSlot. Returns the number of objects deleted.

func (*PebbleEngine) PruneTxHashBefore added in v1.24.1 

func (e *PebbleEngine) PruneTxHashBefore(_ context.Context, maxSlot uint64) (int64, error)

PruneTxHashBefore deletes all index entries for slots below maxSlot using the slot-ordered prune namespace, returning the number of entries removed.

func (*PebbleEngine) PutTxHashes added in v1.24.1 

func (e *PebbleEngine) PutTxHashes(_ context.Context, entries []types.TxHashEntry) error

PutTxHashes writes the lookup and prune-order keys for each entry.

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.