discover

Documentation

Overview

Package discv5 implements the RLPx v5 Topic Discovery Protocol.

The Topic 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

• Constants
• type AbsTime
  • func Now() AbsTime
• type Config
• type Hash
  • func BytesToHash(b []byte) Hash
  • func Sha3256Hash(data ...[]byte) (h Hash)
  • func (h Hash) Bytes() []byte
  • func (h Hash) Hex() string
  • func (h *Hash) SetBytes(b []byte)
  • func (h Hash) Str() string
• type Network
  • func ListenUDP(priv *crypto.PrivKeyEd25519, conn conn, db NetworkDB, ...) (*Network, error)
  • func (net *Network) Close()
  • func (net *Network) Lookup(targetID NodeID) []*Node
  • func (net *Network) ReadRandomNodes(buf []*Node) (n int)
  • func (net *Network) RegisterTopic(topic Topic, stop <-chan struct{})
  • func (net *Network) Resolve(targetID NodeID) *Node
  • func (net *Network) SearchTopic(topic Topic, setPeriod <-chan time.Duration, found chan<- *Node, ...)
  • func (net *Network) Self() *Node
  • func (net *Network) SetFallbackNodes(nodes []*Node) error
• type NetworkDB
  • func NewNetworkDB(cfg *config.Config, self NodeID) (NetworkDB, error)
• type Node
  • func MustParseNode(rawurl string) *Node
  • func NewNode(id NodeID, ip net.IP, udpPort, tcpPort uint16) *Node
  • func ParseNode(rawurl string) (*Node, error)
  • func (n *Node) Incomplete() bool
  • func (n *Node) MarshalText() ([]byte, error)
  • func (n *Node) String() string
  • func (n *Node) UnmarshalText(text []byte) error
• type NodeID
  • func ByteID(in []byte) NodeID
  • func HexID(in string) (NodeID, error)
  • func MustHexID(in string) NodeID
  • func PubkeyID(pub *ecdsa.PublicKey) NodeID
  • func (n NodeID) GoString() string
  • func (n NodeID) String() string
  • func (n NodeID) TerminalString() string
• type ReadPacket
• type Table
• type Topic

Constants

const (
	HashLength = 32
)

const Version = 4 //TODO: reset it before releasing

Types

type AbsTime

type AbsTime time.Duration // absolute monotonic time

func Now

func Now() AbsTime

type Config

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

	// These settings are optional:
	AnnounceAddr *net.UDPAddr // local address announced in the DHT
	NodeDBPath   string       // if set, the node database is stored at this filesystem location
	//NetRestrict  *netutil.Netlist  // network whitelist
	Bootnodes []*Node           // list of bootstrap nodes
	Unhandled chan<- ReadPacket // unhandled packets are sent on this channel
}

Config holds Table-related settings.

type Hash

type Hash [HashLength]byte

func BytesToHash

func BytesToHash(b []byte) Hash

func Sha3256Hash

func Sha3256Hash(data ...[]byte) (h Hash)

func (Hash) Bytes

func (h Hash) Bytes() []byte

func (Hash) Hex

func (h Hash) Hex() string

func (*Hash) SetBytes

func (h *Hash) SetBytes(b []byte)

Sets the hash to the value of b. If b is larger than len(h) it will panic

func (Hash) Str

func (h Hash) Str() string

type Network

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

Network manages the table and all protocol interaction.

func ListenUDP

func ListenUDP(priv *crypto.PrivKeyEd25519, conn conn, db NetworkDB, netrestrict *netutil.Netlist) (*Network, error)

ListenUDP returns a new table that listens for UDP packets on laddr.

func (*Network) Close

func (net *Network) Close()

Close terminates the network listener and flushes the node database.

func (*Network) Lookup

func (net *Network) Lookup(targetID NodeID) []*Node

Lookup performs a network search for nodes close to the given target. It approaches the target by querying nodes that are closer to it on each iteration. The given target does not need to be an actual node identifier.

The local node may be included in the result.

func (*Network) ReadRandomNodes

func (net *Network) ReadRandomNodes(buf []*Node) (n int)

ReadRandomNodes fills the given slice with random nodes from the table. It will not write the same node more than once. The nodes in the slice are copies and can be modified by the caller.

func (*Network) RegisterTopic

func (net *Network) RegisterTopic(topic Topic, stop <-chan struct{})

func (*Network) Resolve

func (net *Network) Resolve(targetID NodeID) *Node

Resolve searches for a specific node with the given ID. It returns nil if the node could not be found.

func (*Network) SearchTopic

func (net *Network) SearchTopic(topic Topic, setPeriod <-chan time.Duration, found chan<- *Node, lookup chan<- bool)

func (*Network) Self

func (net *Network) Self() *Node

Self returns the local node. The returned node should not be modified by the caller.

func (*Network) SetFallbackNodes

func (net *Network) SetFallbackNodes(nodes []*Node) error

SetFallbackNodes sets the initial points of contact. These nodes are used to connect to the network if the table is empty and there are no known nodes in the database.

type NetworkDB

type NetworkDB interface {
	Get(key []byte) ([]byte, error)
	Put(key, value []byte) error
	Close() error
}

func NewNetworkDB

func NewNetworkDB(cfg *config.Config, self NodeID) (NetworkDB, error)

type Node

type Node struct {
	IP       net.IP // len 4 for IPv4 or 16 for IPv6
	UDP, TCP uint16 // port numbers
	ID       NodeID // the node's public key
	// contains filtered or unexported fields
}

Node represents a host on the network. The public fields of Node may not be modified.

func MustParseNode

func MustParseNode(rawurl string) *Node

MustParseNode parses a node URL. It panics if the URL is not valid.

func NewNode

func NewNode(id NodeID, ip net.IP, udpPort, tcpPort uint16) *Node

NewNode creates a new node. It is mostly meant to be used for testing purposes.

func ParseNode

func ParseNode(rawurl string) (*Node, error)

ParseNode parses a node designator.

There are two basic forms of node designators

• incomplete nodes, which only have the public key (node ID)
• complete nodes, which contain the public key and IP/Port information

For incomplete nodes, the designator must look like one of these

enode://<hex node id>
<hex node id>

For complete nodes, the node ID is encoded in the username portion of the URL, separated from the host by an @ sign. The hostname can only be given as an IP address, DNS domain names are not allowed. The port in the host name section is the TCP listening port. If the TCP and UDP (discovery) ports differ, the UDP port is specified as query parameter "discport".

In the following example, the node URL describes a node with IP address 10.3.58.6, TCP listening port 30303 and UDP discovery port 30301.

enode://<hex node id>@10.3.58.6:30303?discport=30301

func (*Node) Incomplete

func (n *Node) Incomplete() bool

Incomplete returns true for nodes with no IP address.

func (*Node) MarshalText

func (n *Node) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*Node) String

func (n *Node) String() string

The string representation of a Node is a URL. Please see ParseNode for a description of the format.

func (*Node) UnmarshalText

func (n *Node) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type NodeID

type NodeID [32]byte

NodeID is a unique identifier for each node. The node identifier is a marshaled elliptic curve public key.

func ByteID

func ByteID(in []byte) NodeID

ByteID converts a []byte to a NodeID.

func HexID

func HexID(in string) (NodeID, error)

HexID converts a hex string to a NodeID. The string may be prefixed with 0x.

func MustHexID

func MustHexID(in string) NodeID

MustHexID converts a hex string to a NodeID. It panics if the string is not a valid NodeID.

func PubkeyID

func PubkeyID(pub *ecdsa.PublicKey) NodeID

PubkeyID returns a marshaled representation of the given public key.

func (NodeID) GoString

func (n NodeID) GoString() string

The Go syntax representation of a NodeID is a call to HexID.

func (NodeID) String

func (n NodeID) String() string

NodeID prints as a long hexadecimal number.

func (NodeID) TerminalString

func (n NodeID) TerminalString() string

TerminalString returns a shortened hex string for terminal logging.

type ReadPacket

type ReadPacket struct {
	Data []byte
	Addr *net.UDPAddr
}

ReadPacket is sent to the unhandled channel when it could not be processed

type Table

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

type Topic

type Topic string