externs.go

package dasmon

import (
	"context"

	"github.com/libp2p/go-libp2p/core/peer"
)

// Externs provides external beacon client functionality.
// This is the single interface that integrators must implement to plug their
// beacon client into dasmon. All beacon-client-specific logic (database queries,
// peer metadata access, chain event subscriptions) is abstracted through this interface.
//
// Example implementation for Prysm is provided in adapters/prysm/prysm_externs.go.
type Externs interface {
	// PeerRefresh retrieves both metadata and status for a peer.
	// This includes the custody group count, peer-specific configuration,
	// and the peer's view of the head slot and earliest available slot.
	PeerRefresh(ctx context.Context, id peer.ID) (*PeerCustody, error)

	// ChainQuery retrieves blocks in the specified slot range.
	// Returns blocks sorted by slot number with their KZG commitments.
	ChainQuery(ctx context.Context, query BlockQuery) ([]*Block, error)

	// ChainHead retrieves the current head block and its root.
	// This is used for initialization and tracking chain progression.
	ChainHead(ctx context.Context) (block *Block, root [32]byte, err error)

	// ChainSubscribe returns a channel that receives chain events.
	// The channel receives events when new blocks are finalized or reorgs occur.
	// The channel is closed when the context is cancelled.
	// Maps to: stateNotifier.StateFeed().Subscribe()
	//
	// The returned channel must be buffered to prevent blocking the event source.
	// Implementers should handle context cancellation and clean up subscriptions.
	ChainSubscribe(ctx context.Context) (<-chan ChainEvent, error)
}