ethereum

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

type BeaconNodeAPI interface {
	// Start starts the beacon node and blocks until it is healthy.
	Start(ctx context.Context) error
	// Stop stops the beacon node.
	Stop(ctx context.Context) error
	// Synced checks if the beacon node is synced and ready.
	Synced(ctx context.Context) error
}

type BeaconOptions struct {
	TraceID       string
	Config        *Config
	Sinks         []sinks.ContributoorSink
	Cache         *events.DuplicateCache
	Summary       *events.Summary
	Metrics       *events.Metrics
	TopicManager  TopicManager
	ExcludeTopics []string
}

type BeaconWrapper struct {
	*ethcore.BeaconNode // Embed ethcore beacon
	// contains filtered or unexported fields
}

type Config struct {
	// The address of the Beacon node to connect to.
	BeaconNodeAddress string `yaml:"beaconNodeAddress"`
	// BeaconNodeHeaders is a map of headers to send to the beacon node.
	BeaconNodeHeaders map[string]string `yaml:"beaconNodeHeaders"`
	// NetworkOverride is an optional network name to use instead of what's reported by the beacon node.
	NetworkOverride string `yaml:"networkOverride,omitempty"`
	// AttestationSubnetConfig controls attestation subnet-based subscription filtering.
	AttestationSubnetConfig SubnetConfig `yaml:"attestationSubnet"`
}

type NodeIdentity interface {
	// Start fetches and stores the node identity.
	Start(ctx context.Context) error
	// Stop performs cleanup.
	Stop() error
	// GetAttnets returns the list of subscribed attestation subnet IDs.
	GetAttnets() []int
}

type NodeIdentityData struct {
	PeerID             string               `json:"peer_id"` //nolint:tagliatelle // beacon API uses snake_case
	ENR                string               `json:"enr"`
	P2PAddresses       []string             `json:"p2p_addresses"`       //nolint:tagliatelle // beacon API uses snake_case
	DiscoveryAddresses []string             `json:"discovery_addresses"` //nolint:tagliatelle // beacon API uses snake_case
	Metadata           NodeIdentityMetadata `json:"metadata"`
}

type NodeIdentityMetadata struct {
	SeqNumber         string `json:"seq_number"` //nolint:tagliatelle // beacon API uses snake_case
	Attnets           string `json:"attnets"`
	Syncnets          string `json:"syncnets"`
	CustodyGroupCount string `json:"custody_group_count"` //nolint:tagliatelle // beacon API uses snake_case
}

type SubnetConfig struct {
	// Enabled controls whether to check subnet participation at startup.
	Enabled bool `yaml:"enabled"`
	// MaxSubnets is the maximum number of subnets the node participates in.
	MaxSubnets int `yaml:"maxSubnets"`
	// MismatchDetectionWindow is the number of slots to track for subnet activity.
	MismatchDetectionWindow int `yaml:"mismatchDetectionWindow"`
	// MismatchThreshold is the number of mismatches required before triggering reconnection.
	MismatchThreshold int `yaml:"mismatchThreshold"`
	// MismatchCooldownSeconds is the cooldown period between reconnections in seconds.
	MismatchCooldownSeconds int `yaml:"mismatchCooldownSeconds"`
	// SubnetHighWaterMark allows temporary participation in additional subnets
	// without triggering a restart. This accommodates validators temporarily
	// joining subnets to submit attestations while protecting privacy.
	SubnetHighWaterMark int `yaml:"subnetHighWaterMark"`
}

type TopicCondition func(ctx context.Context) (bool, error)

type TopicConfig struct {
	// AllTopics
	AllTopics []string
	// OptInTopics
	OptInTopics []string
	// AttestationEnabled controls if attestation subnet checking is enabled.
	AttestationEnabled bool
	// AttestationMaxSubnets is the max subnets before disabling single_attestation.
	AttestationMaxSubnets int
	// MismatchDetectionWindow is the number of slots to track.
	MismatchDetectionWindow int
	// MismatchThreshold is the number of mismatches before reconnection.
	MismatchThreshold int
	// MismatchCooldown is the cooldown period between reconnections.
	MismatchCooldown time.Duration
	// SubnetHighWaterMark is the threshold for temporary subnet participation.
	SubnetHighWaterMark int
}

type TopicManager interface {
	RegisterCondition(topic string, condition TopicCondition)
	ShouldSubscribe(ctx context.Context, topic string) bool
	GetEnabledTopics(ctx context.Context) []string
	ExcludeTopic(topic string)
	IsExcluded(topic string) bool
	SetAdvertisedSubnets(subnets []int)
	RecordAttestation(subnetID uint64, slot phase0.Slot)
	IsActiveSubnet(subnetID uint64) bool
	NeedsReconnection() <-chan struct{}
	ResetAfterReconnection()
	GetCooldownPeriod() time.Duration
	StartSubnetRefresh(ctx context.Context, refreshInterval time.Duration, nodeIdentityFetcher func() []int)
	StopSubnetRefresh()
}