protocol

type ENRRequest struct {
	// Expiration is the UNIX timestamp when this packet expires
	Expiration uint64

	// Rest allows forward compatibility
	Rest []rlp.RawValue `rlp:"tail"`
}

type ENRResponse struct {
	// ReplyTok is the hash of the ENRREQUEST packet we're responding to
	ReplyTok []byte

	// Record is the sender's ENR record
	Record *enr.Record

	// Rest allows forward compatibility
	Rest []rlp.RawValue `rlp:"tail"`
}

type Endpoint struct {
	// IP is the IP address (4 bytes for IPv4, 16 for IPv6)
	IP net.IP

	// UDP is the UDP port
	UDP uint16

	// TCP is the TCP port
	TCP uint16
}

type Findnode struct {
	// Target is the public key we're searching for neighbors of
	// The response should contain nodes close to this target
	Target Pubkey

	// Expiration is the UNIX timestamp when this packet expires
	Expiration uint64

	// Rest allows forward compatibility
	Rest []rlp.RawValue `rlp:"tail"`
}

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

type HandlerConfig struct {
	// PrivateKey is our node's private key
	PrivateKey *ecdsa.PrivateKey

	// LocalENR is our node's ENR record (optional). It seeds the handler's
	// record; SetLocalENR replaces it while running, so handler code must read
	// LocalRecord() rather than this field.
	LocalENR *enr.Record

	// LocalAddr is our listening address
	LocalAddr *net.UDPAddr

	// BondExpiration is how long bonds last (default 24 hours)
	BondExpiration time.Duration

	// RequestTimeout is how long to wait for responses (default 500ms)
	RequestTimeout time.Duration

	// ExpirationWindow is the acceptable time range for packet expiration (default 20s)
	ExpirationWindow time.Duration

	// MaxNodes is the maximum number of nodes to track (default 50000).
	// Once reached, new nodes are handled but not retained until a slot frees up,
	// keeping memory bounded under floods of distinct node IDs.
	MaxNodes int

	// NodeTTL is how long an unbonded node is retained since it was last seen
	// before it becomes eligible for eviction (default 5 minutes). Bonded nodes
	// are kept until their bond expires.
	NodeTTL time.Duration

	// Callbacks (all optional)
	OnPing         OnPingCallback
	OnPongReceived OnPongReceivedCallback
	OnFindnode     OnFindnodeCallback
	OnENRRequest   OnENRRequestCallback
	OnNodeSeen     OnNodeSeenCallback
}

type HandlerStats struct {
	PacketsReceived       uint64
	PacketsSent           uint64
	InvalidPackets        uint64
	ExpiredPackets        uint64
	UnbondedFindnode      uint64
	FindnodeRequestsRecv  uint64
	FindnodeResponsesRecv uint64
	KnownNodes            int
	PendingRequests       int
	PendingNeighbors      int
}

type Neighbors struct {
	// Nodes is the list of nodes close to the target
	Nodes []NodeRecord

	// Expiration is the UNIX timestamp when this packet expires
	Expiration uint64

	// Rest allows forward compatibility
	Rest []rlp.RawValue `rlp:"tail"`
}

type NodeRecord struct {
	// IP is the node's IP address (4 bytes for IPv4, 16 for IPv6)
	IP net.IP

	// UDP is the UDP port for discovery
	UDP uint16

	// TCP is the TCP port for RLPx
	TCP uint16

	// ID is the node's public key
	ID Pubkey
}

type OnENRRequestCallback func(from *node.Node) error

type OnFindnodeCallback func(from *node.Node, target []byte, requester *net.UDPAddr) []*node.Node

type OnNodeSeenCallback func(n *node.Node, timestamp time.Time)

type OnPingCallback func(from *node.Node, ping *Ping) error

type OnPongReceivedCallback func(from *node.Node, provenAddr *net.UDPAddr, ip net.IP, port uint16)

type Packet interface {
	// Name returns the packet name for logging
	Name() string
	// Kind returns the packet type byte
	Kind() byte
}

type PendingNeighborsResponse struct {
	// Nodes accumulated so far
	Nodes []*node.Node

	// Reserved counts nodes a handler has claimed room for but may not have
	// appended yet. Reserving before decoding makes the persistence cap exact
	// even when packets are dispatched concurrently.
	Reserved int

	// Closed marks a delivered entry. Packets processed after delivery must
	// not reserve against it; cleanup evicts the tombstone by CreatedAt.
	Closed bool

	// CreatedAt is when we received the first packet
	CreatedAt time.Time
}

type PendingRequest struct {
	// RequestHash is the hash of the outgoing packet (used as reply token)
	RequestHash []byte

	// ToNode is the destination node
	ToNode *node.Node

	// DestIP is the IP the request was sent to, snapshotted at send time; see
	// lookupOrCreateNode. ToNode.Addr() cannot serve here because promoteAddr can
	// move it between send and response.
	DestIP net.IP

	// PacketType is the type of request
	PacketType byte

	// CreatedAt is when the request was created
	CreatedAt time.Time

	// Timeout is when the request expires
	Timeout time.Time

	// ResponseChan receives the response (or nil on timeout)
	ResponseChan chan interface{}
}

type Ping struct {
	// Version is the discovery protocol version (currently 4)
	Version uint

	// From is the sender's endpoint information
	From Endpoint

	// To is the recipient's endpoint (as known by sender)
	To Endpoint

	// Expiration is the UNIX timestamp when this packet expires
	Expiration uint64

	// ENRSeq is the sender's ENR sequence number (optional, EIP-868)
	ENRSeq uint64 `rlp:"optional"`

	// Rest allows forward compatibility with future fields
	Rest []rlp.RawValue `rlp:"tail"`
}

type Pong struct {
	// To is the recipient's endpoint as seen by the sender
	// This allows the recipient to discover their external address
	To Endpoint

	// ReplyTok is the hash of the PING packet we're responding to
	// This allows the requester to match PONG to PING
	ReplyTok []byte

	// Expiration is the UNIX timestamp when this packet expires
	Expiration uint64

	// ENRSeq is the sender's ENR sequence number (optional, EIP-868)
	ENRSeq uint64 `rlp:"optional"`

	// Rest allows forward compatibility
	Rest []rlp.RawValue `rlp:"tail"`
}

type Pubkey [64]byte

type Transport interface {
	SendTo(data []byte, to *net.UDPAddr) error
	Send(data []byte, to *net.UDPAddr, from *net.UDPAddr) error
}