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 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)

	// 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
}

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

	// Committees[slotIndex][committeeIndex] holds the global validator indices
	// of that committee in attestation-bit order.
	Committees [][][]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
}

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
	Output  []byte
	Error   string
}

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 StateChangeAccount struct {
	Address [20]byte
	Flags   uint8

	// Balance
	PreBalance  uint256.Int
	PostBalance uint256.Int

	// Nonce
	PreNonce  uint64
	PostNonce uint64

	// Code
	PreCode  []byte
	PostCode []byte

	// Storage
	Slots []StateChangeSlot
}

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)
}