types

type BlockData struct {
	// Header data
	HeaderVersion uint64
	HeaderData    []byte

	// Body data
	BodyVersion uint64
	BodyData    []byte
	Body        any // Parsed body (optional)

	// Execution payload data (ePBS)
	PayloadVersion uint64
	PayloadData    []byte
	Payload        any // Parsed payload (optional)

	// Block access list data
	BalVersion uint64
	BalData    []byte
}

type BlockDataFlags uint8

type BlockDbEngine interface {
	// Close closes the database engine.
	Close() error

	// GetBlock retrieves block data with selective loading based on flags.
	// If parseBlock is nil, raw body data is stored in BlockData.BodyData.
	// If parsePayload is nil, raw payload data is stored in BlockData.PayloadData.
	GetBlock(
		ctx context.Context,
		slot uint64,
		root []byte,
		flags BlockDataFlags,
		parseBlock func(uint64, []byte) (any, error),
		parsePayload func(uint64, []byte) (any, error),
	) (*BlockData, error)

	// AddBlock stores block data. Returns:
	// - added: true if a new block was created
	// - updated: true if an existing block was updated with new components
	AddBlock(
		ctx context.Context,
		slot uint64,
		root []byte,
		dataCb func() (*BlockData, error),
	) (added bool, updated bool, err error)

	// GetStoredComponents returns which components exist for a block.
	GetStoredComponents(ctx context.Context, slot uint64, root []byte) (BlockDataFlags, error)
}

type BlockDbObjectStats struct {
	// BlockCount is the number of block header records (namespace ns1), which
	// includes both canonical and orphaned blocks (they share the namespace).
	BlockCount uint64
	// CanonicalDutiesCount is the number of canonical per-epoch duties objects.
	CanonicalDutiesCount uint64
	// DivergingDutiesCount is the number of diverging-fork duties objects.
	DivergingDutiesCount uint64
	// BidsCount is the number of per-slot bids objects (namespace ns7).
	BidsCount uint64
	// BidsBytes is the total encoded size of the bids objects, if available.
	BidsBytes uint64
}

type BlockReceiptMeta struct {
	Version      uint16 // Schema version for forward compatibility
	BlobGasPrice uint64 // Block-wide blob gas price in wei (EIP-4844), 0 if not applicable
}

type DutiesEngine interface {
	// AddEpochDuties stores the resolved duties for an epoch.
	// Returns the stored size in bytes.
	AddEpochDuties(ctx context.Context, duties *EpochDuties) (int64, error)

	// GetEpochDuties retrieves the full resolved duties for an epoch.
	// Returns nil, nil if not found. Used for whole-epoch copies.
	GetEpochDuties(ctx context.Context, firstSlot uint64) (*EpochDuties, error)

	// AddDivergingEpochDuties stores the resolved duties of a diverging fork,
	// keyed additionally by duties.DependentRoot (which must be non-zero).
	// Returns the stored size in bytes.
	AddDivergingEpochDuties(ctx context.Context, duties *EpochDuties) (int64, error)

	// GetEpochDutiesForRoot retrieves the full diverging-fork duties for an epoch
	// under the given dependent root. Returns nil, nil if not found.
	GetEpochDutiesForRoot(ctx context.Context, firstSlot uint64, depRoot [32]byte) (*EpochDuties, error)

	// GetSlotCommitteesForRoot returns the attester committees for a single slot
	// of the diverging fork identified by depRoot. Returns nil, nil if not found.
	GetSlotCommitteesForRoot(ctx context.Context, firstSlot uint64, slot uint64, depRoot [32]byte) ([][]uint64, error)

	// GetSlotPtcForRoot returns the PTC members for a single slot of the
	// diverging fork identified by depRoot. Returns nil, nil if not found.
	GetSlotPtcForRoot(ctx context.Context, firstSlot uint64, slot uint64, depRoot [32]byte) ([]uint64, error)

	// GetSlotCommittees returns the attester committees for a single slot
	// (global validator indices, in committee order). firstSlot identifies the
	// epoch object. Returns nil, nil if not found.
	GetSlotCommittees(ctx context.Context, firstSlot uint64, slot uint64) ([][]uint64, error)

	// GetSlotPtc returns the PTC members for a single slot (global validator
	// indices). Returns nil, nil if not found or the epoch has no PTC.
	GetSlotPtc(ctx context.Context, firstSlot uint64, slot uint64) ([]uint64, error)

	// HasEpochDuties checks if duties exist for an epoch.
	HasEpochDuties(ctx context.Context, firstSlot uint64) (bool, error)

	// PruneEpochDutiesBefore deletes duties for all epochs whose first slot is
	// before maxFirstSlot. Returns the number of epochs deleted.
	PruneEpochDutiesBefore(ctx context.Context, maxFirstSlot uint64) (int64, error)
}

type DutiesHeader struct {
	Version           uint16
	Flags             uint8
	IndexWidth        uint8
	Epoch             uint64
	ValidatorCount    uint64
	SlotsPerEpoch     uint64
	CommitteesPerSlot uint64
	PtcSize           uint64
	// DependentRoot is the committee-shuffling dependent root. Non-zero only in
	// v2 (diverging-fork) objects; zero for v1 (canonical) objects.
	DependentRoot [32]byte
}

type EpochDuties struct {
	FirstSlot         uint64
	Epoch             uint64
	ValidatorCount    uint64
	SlotsPerEpoch     uint64
	CommitteesPerSlot uint64
	PtcSize           uint64

	// DependentRoot is the committee-shuffling dependent root of the fork these
	// duties belong to. Set for v2 objects (both canonical and diverging); zero
	// for legacy v1 objects.
	DependentRoot [32]byte

	// Diverging marks the object as belonging to a non-canonical fork (sets the
	// DutiesFlagDiverging header flag). Purely informational: keying already
	// distinguishes canonical (firstSlot) from diverging (firstSlot, depRoot).
	Diverging bool

	// Committees[slotIndex][committeeIndex] holds the global validator indices
	// of that committee in attestation-bit order.
	Committees [][][]uint64
	// ProposerDuties[slotIndex] holds the global validator index of the slot's
	// proposer. Length SlotsPerEpoch in v2; nil for v1. Unknown/out-of-range
	// proposers are stored as 0.
	ProposerDuties []uint64
	// Ptc[slotIndex] holds the PTC members (global validator indices), each
	// slice exactly PtcSize long. Nil if PtcSize == 0.
	Ptc [][]uint64
}

type EventData struct {
	EventIndex uint32
	Source     [20]byte
	Topics     [][]byte `ssz-size:"?,32" ssz-max:"5"`
	Data       []byte   `ssz-max:"10485760"`
}

type EventDataList []EventData

type ExecDataEngine interface {
	// AddExecData stores execution data for a block.
	// Returns the stored object size in bytes.
	AddExecData(ctx context.Context, slot uint64, blockRoot []byte, data []byte) (int64, error)

	// GetExecData retrieves full execution data for a block.
	// Returns nil, nil if not found.
	GetExecData(ctx context.Context, slot uint64, blockRoot []byte) ([]byte, error)

	// GetExecDataRange retrieves a byte range of execution data.
	// For S3: uses Range header. For Pebble: reads full value and slices.
	// Returns nil, nil if not found.
	GetExecDataRange(ctx context.Context, slot uint64, blockRoot []byte, offset int64, length int64) ([]byte, error)

	// GetExecDataTxSections retrieves compressed section data for a single
	// transaction without loading the entire exec data object.
	// sections is a bitmask of ExecDataSection* constants selecting which
	// sections to return. Contiguous requested sections are fetched in a
	// single range read (S3) or key lookup (Pebble).
	// Returns nil, nil if the transaction is not found.
	GetExecDataTxSections(ctx context.Context, slot uint64, blockRoot []byte, txHash []byte, sections uint32) (*ExecDataTxSections, error)

	// HasExecData checks if execution data exists for a block.
	HasExecData(ctx context.Context, slot uint64, blockRoot []byte) (bool, error)

	// DeleteExecData deletes execution data for a specific block.
	DeleteExecData(ctx context.Context, slot uint64, blockRoot []byte) error

	// PruneExecDataBefore deletes execution data for all slots before maxSlot.
	// Returns the number of objects deleted.
	PruneExecDataBefore(ctx context.Context, maxSlot uint64) (int64, error)
}

type ExecDataObject struct {
	FormatVersion uint16
	Flags         uint16
	BlockSlot     uint64
	BlockNumber   uint64

	// Block-level metadata section pointer.
	BlockMetaOffset    uint64
	BlockMetaCompLen   uint32
	BlockMetaUncompLen uint32

	Transactions []ExecDataTxEntry
}

type ExecDataTxEntry struct {
	TxHash         [32]byte
	SectionsBitmap uint32

	ReceiptMetaOffset    uint64
	ReceiptMetaCompLen   uint32
	ReceiptMetaUncompLen uint32

	EventsOffset    uint64
	EventsCompLen   uint32
	EventsUncompLen uint32

	CallTraceOffset    uint64
	CallTraceCompLen   uint32
	CallTraceUncompLen uint32

	StateChangeOffset    uint64
	StateChangeCompLen   uint32
	StateChangeUncompLen uint32
}

type ExecDataTxSectionData struct {
	TxHash [32]byte

	// Compressed section data (nil if section not present)
	ReceiptMetaData []byte
	EventsData      []byte
	CallTraceData   []byte
	StateChangeData []byte

	// Uncompressed lengths (for the index)
	ReceiptMetaUncompLen uint32
	EventsUncompLen      uint32
	CallTraceUncompLen   uint32
	StateChangeUncompLen uint32
}

type ExecDataTxSections struct {
	ReceiptMetaData []byte // snappy-compressed, nil if section not present
	EventsData      []byte // snappy-compressed, nil if section not present
	CallTraceData   []byte // snappy-compressed, nil if section not present
	StateChangeData []byte // snappy-compressed, nil if section not present
}

type FlatCallFrame struct {
	Depth   uint16
	Type    uint8 // CallType* constants
	From    [20]byte
	To      [20]byte
	Value   uint256.Int // nil or zero means no value
	Gas     uint64
	GasUsed uint64
	Status  uint8  // CallStatus* constants
	Input   []byte `ssz-max:"10485760"`
	Output  []byte `ssz-max:"10485760"`
	Error   string `ssz-max:"10485760"`
}

type ObjectStatsEngine interface {
	// GetObjectStats returns per-namespace object counts.
	GetObjectStats(ctx context.Context) (*BlockDbObjectStats, error)
}

type ReceiptMetaData struct {
	Version           uint16      // Schema version for forward compatibility
	Status            uint8       // 0=failure, 1=success
	TxType            uint8       // Transaction type (0=legacy, 1=access list, 2=dynamic fee, 3=blob, 4=set code)
	CumulativeGasUsed uint64      // Cumulative gas used in block up to and including this tx
	GasUsed           uint64      // Gas used by this specific transaction
	EffectiveGasPrice uint256.Int // Actual gas price paid (in wei)
	BlobGasUsed       uint64      // Blob gas used (EIP-4844), 0 otherwise
	LogsBloom         [256]byte   // Bloom filter for this receipt's logs
	From              [20]byte    // Sender address
	To                [20]byte    // Receiver address (zero for contract creation)
	ContractAddress   [20]byte    // Created contract address (zero if not creation)
	HasContractAddr   bool        // Whether ContractAddress is valid (contract creation tx)
}

type SlotBids struct {
	Slot    uint64
	Clients []string
	Bids    []*SlotBidsEntry
}

type SlotBidsEngine interface {
	// AddSlotBids stores the bids object for a slot, replacing any existing
	// object. Returns the stored size in bytes.
	AddSlotBids(ctx context.Context, bids *SlotBids) (int64, error)

	// GetSlotBids retrieves the bids object for a slot.
	// Returns nil, nil if not found.
	GetSlotBids(ctx context.Context, slot uint64) (*SlotBids, error)

	// PruneSlotBidsBefore deletes bids objects for all slots before maxSlot.
	// Returns the number of objects deleted.
	PruneSlotBidsBefore(ctx context.Context, maxSlot uint64) (int64, error)
}

type SlotBidsEntry struct {
	Bid *dbtypes.BlockBid
	// SeenMask bit i is set if the client at table index i observed the bid.
	SeenMask []byte
	// SeenTimes holds one first-seen offset (ms from slot start) per set mask
	// bit, in ascending client index order.
	SeenTimes []int32
}

type StateChangeAccount struct {
	Address [20]byte
	Flags   uint8

	// Balance
	PreBalance  uint256.Int
	PostBalance uint256.Int

	// Nonce
	PreNonce  uint64
	PostNonce uint64

	// Code
	PreCode  []byte `ssz-max:"10485760"`
	PostCode []byte `ssz-max:"10485760"`

	// Storage
	Slots []StateChangeSlot `ssz-max:"10485760"`
}

type StateChangeSlot struct {
	Slot      [32]byte
	PreValue  [32]byte
	PostValue [32]byte
}

type TxHashEntry struct {
	Prefix []byte // TxHashPrefixLen bytes
	TxUid  uint64 // slot<<32 | block_index<<16 | tx_index
}

type TxHashIndex interface {
	// PutTxHashes inserts (idempotently) one entry per transaction.
	PutTxHashes(ctx context.Context, entries []TxHashEntry) error
	// LookupTxHash returns all candidate tx_uids for an exact prefix.
	LookupTxHash(ctx context.Context, prefix []byte) ([]uint64, error)
	// LookupTxHashRange returns candidate tx_uids for prefixes in [lo, hi),
	// used for partial-hash search.
	LookupTxHashRange(ctx context.Context, lo, hi []byte) ([]uint64, error)
	// PruneTxHashBefore removes all entries for slots below maxSlot and returns
	// the number of entries removed.
	PruneTxHashBefore(ctx context.Context, maxSlot uint64) (int64, error)
}