discover

Documentation

Overview

Package discover implements the Node Discovery Protocol.

The Node Discovery protocol provides a way to find RLPx nodes that can be connected to. It uses a Kademlia-like protocol to maintain a distributed database of the IDs and endpoints of all listening nodes.

Index

• type BucketNode
• type Config
• type ReadPacket
• type Table
  • func (tab *Table) Nodes() [][]BucketNode
• type TalkRequestHandler
• type UDPConn
• type UDPv4
  • func ListenUDP(c UDPConn, ln *enode.LocalNode, cfg Config) (*UDPv4, error)
  • func ListenV4(c UDPConn, ln *enode.LocalNode, cfg Config) (*UDPv4, error)
  • func (t *UDPv4) Close()
  • func (t *UDPv4) LookupPubkey(key *ecdsa.PublicKey) []*enode.Node
  • func (t *UDPv4) Ping(n *enode.Node) error
  • func (t *UDPv4) RandomNodes() enode.Iterator
  • func (t *UDPv4) RequestENR(n *enode.Node) (*enode.Node, error)
  • func (t *UDPv4) Resolve(n *enode.Node) *enode.Node
  • func (t *UDPv4) Self() *enode.Node
  • func (t *UDPv4) TableBuckets() [][]BucketNode
• type UDPv5
  • func ListenV5(conn UDPConn, ln *enode.LocalNode, cfg Config) (*UDPv5, error)
  • func (t *UDPv5) AllNodes() []*enode.Node
  • func (t *UDPv5) Close()
  • func (t *UDPv5) LocalNode() *enode.LocalNode
  • func (t *UDPv5) Lookup(target enode.ID) []*enode.Node
  • func (t *UDPv5) Ping(n *enode.Node) error
  • func (t *UDPv5) RandomNodes() enode.Iterator
  • func (t *UDPv5) RegisterTalkHandler(protocol string, handler TalkRequestHandler)
  • func (t *UDPv5) RequestENR(n *enode.Node) (*enode.Node, error)
  • func (t *UDPv5) Resolve(n *enode.Node) *enode.Node
  • func (t *UDPv5) Self() *enode.Node
  • func (t *UDPv5) TalkRequest(n *enode.Node, protocol string, request []byte) ([]byte, error)
  • func (t *UDPv5) TalkRequestToID(id enode.ID, addr netip.AddrPort, protocol string, request []byte) ([]byte, error)

Types

type BucketNode

type BucketNode struct {
	Node          *enode.Node `json:"node"`
	AddedToTable  time.Time   `json:"addedToTable"`
	AddedToBucket time.Time   `json:"addedToBucket"`
	Checks        int         `json:"checks"`
	Live          bool        `json:"live"`
}

type Config

type Config struct {
	// These settings are required and configure the UDP listener:
	PrivateKey *ecdsa.PrivateKey

	// Packet handling configuration:
	NetRestrict *netutil.Netlist  // list of allowed IP networks
	Unhandled   chan<- ReadPacket // unhandled packets are sent on this channel

	// Node table configuration:
	Bootnodes       []*enode.Node // list of bootstrap nodes
	PingInterval    time.Duration // speed of node liveness check
	RefreshInterval time.Duration // used in bucket refresh

	// The options below are useful in very specific cases, like in unit tests.
	V5ProtocolID *[6]byte
	Log          log.Logger         // if set, log messages go here
	ValidSchemes enr.IdentityScheme // allowed identity schemes
	Clock        mclock.Clock
}

Config holds settings for the discovery listener.

type ReadPacket

type ReadPacket struct {
	Data []byte
	Addr netip.AddrPort
}

ReadPacket is a packet that couldn't be handled. Those packets are sent to the unhandled channel if configured.

type Table

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

Table is the 'node table', a Kademlia-like index of neighbor nodes. The table keeps itself up-to-date by verifying the liveness of neighbors and requesting their node records when announcements of a new record version are received.

func (*Table) Nodes

func (tab *Table) Nodes() [][]BucketNode

Nodes returns all nodes contained in the table.

type TalkRequestHandler

type TalkRequestHandler func(enode.ID, *net.UDPAddr, []byte) []byte

TalkRequestHandler callback processes a talk request and returns a response.

Note that talk handlers are expected to come up with a response very quickly, within at most 200ms or so. If the handler takes longer than that, the remote end may time out and wont receive the response.

type UDPConn

type UDPConn interface {
	ReadFromUDPAddrPort(b []byte) (n int, addr netip.AddrPort, err error)
	WriteToUDPAddrPort(b []byte, addr netip.AddrPort) (n int, err error)
	Close() error
	LocalAddr() net.Addr
}

UDPConn is a network connection on which discovery can operate.

type UDPv4

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

UDPv4 implements the v4 wire protocol.

func ListenUDP

func ListenUDP(c UDPConn, ln *enode.LocalNode, cfg Config) (*UDPv4, error)

ListenUDP starts listening for discovery packets on the given UDP socket.

func ListenV4

func ListenV4(c UDPConn, ln *enode.LocalNode, cfg Config) (*UDPv4, error)

func (*UDPv4) Close

func (t *UDPv4) Close()

Close shuts down the socket and aborts any running queries.

func (*UDPv4) LookupPubkey

func (t *UDPv4) LookupPubkey(key *ecdsa.PublicKey) []*enode.Node

LookupPubkey finds the closest nodes to the given public key.

func (*UDPv4) Ping

func (t *UDPv4) Ping(n *enode.Node) error

Ping sends a ping message to the given node.

func (*UDPv4) RandomNodes

func (t *UDPv4) RandomNodes() enode.Iterator

RandomNodes is an iterator yielding nodes from a random walk of the DHT.

func (*UDPv4) RequestENR

func (t *UDPv4) RequestENR(n *enode.Node) (*enode.Node, error)

RequestENR sends ENRRequest to the given node and waits for a response.

func (*UDPv4) Resolve

func (t *UDPv4) Resolve(n *enode.Node) *enode.Node

Resolve searches for a specific node with the given ID and tries to get the most recent version of the node record for it. It returns n if the node could not be resolved.

func (*UDPv4) Self

func (t *UDPv4) Self() *enode.Node

Self returns the local node.

func (*UDPv4) TableBuckets

func (t *UDPv4) TableBuckets() [][]BucketNode

type UDPv5

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

UDPv5 is the implementation of protocol version 5.

func ListenV5

func ListenV5(conn UDPConn, ln *enode.LocalNode, cfg Config) (*UDPv5, error)

ListenV5 listens on the given connection.

func (*UDPv5) AllNodes

func (t *UDPv5) AllNodes() []*enode.Node

AllNodes returns all the nodes stored in the local table.

func (*UDPv5) Close

func (t *UDPv5) Close()

Close shuts down packet processing.

func (*UDPv5) LocalNode

func (t *UDPv5) LocalNode() *enode.LocalNode

LocalNode returns the current local node running the protocol.

func (*UDPv5) Lookup

func (t *UDPv5) Lookup(target enode.ID) []*enode.Node

Lookup performs a recursive lookup for the given target. It returns the closest nodes to target.

func (*UDPv5) Ping

func (t *UDPv5) Ping(n *enode.Node) error

Ping sends a ping message to the given node.

func (*UDPv5) RandomNodes

func (t *UDPv5) RandomNodes() enode.Iterator

RandomNodes returns an iterator that finds random nodes in the DHT.

func (*UDPv5) RegisterTalkHandler

func (t *UDPv5) RegisterTalkHandler(protocol string, handler TalkRequestHandler)

RegisterTalkHandler adds a handler for 'talk requests'. The handler function is called whenever a request for the given protocol is received and should return the response data or nil.

func (*UDPv5) RequestENR

func (t *UDPv5) RequestENR(n *enode.Node) (*enode.Node, error)

RequestENR requests n's record.

func (*UDPv5) Resolve

func (t *UDPv5) Resolve(n *enode.Node) *enode.Node

Resolve searches for a specific node with the given ID and tries to get the most recent version of the node record for it. It returns n if the node could not be resolved.

func (*UDPv5) Self

func (t *UDPv5) Self() *enode.Node

Self returns the local node record.

func (*UDPv5) TalkRequest

func (t *UDPv5) TalkRequest(n *enode.Node, protocol string, request []byte) ([]byte, error)

TalkRequest sends a talk request to a node and waits for a response.

func (*UDPv5) TalkRequestToID

func (t *UDPv5) TalkRequestToID(id enode.ID, addr netip.AddrPort, protocol string, request []byte) ([]byte, error)

TalkRequestToID sends a talk request to a node and waits for a response.