discover

package
v1.0.3-rc.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 24, 2024 License: GPL-3.0 Imports: 35 Imported by: 0

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

Examples

Constants

View Source 
const (
	NodeTypeUnknown = NodeType(iota)
	NodeTypeCN
	NodeTypePN
	NodeTypeEN
	NodeTypeBN
)

Node types

View Source 
const NodeIDBits = 512
View Source 
const Version = 4

Variables

This section is empty.

Functions

func NewSimpleStorage 

func NewSimpleStorage(nodeType NodeType, noDiscover bool, max int, authorizedNodes []*Node) *simpleStorage

func StringNodeType 

func StringNodeType(nType NodeType) string

StringNodeType converts NodeType to string

Types

type Config 

type Config struct {
	NetworkID uint64
	// 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

	// These settings are required for create Table and UDP
	Id   NodeID
	Addr *net.UDPAddr

	Conn     conn
	NodeType NodeType

	// These settings are required for discovery packet control
	MaxNeighborsNode uint
	AuthorizedNodes  []*Node
	// contains filtered or unexported fields
}

Config holds Table-related settings.

type Discovery 

type Discovery interface {
	Self() *Node
	Close()
	Resolve(target NodeID, targetType NodeType) *Node
	Lookup(target NodeID, targetType NodeType) []*Node
	GetNodes(targetType NodeType, max int) []*Node
	ReadRandomNodes([]*Node, NodeType) int
	RetrieveNodes(target common.Hash, nType NodeType, nresults int) []*Node // replace of closest():Table

	HasBond(id NodeID) bool
	Bond(pinged bool, id NodeID, addr *net.UDPAddr, tcpPort uint16, nType NodeType) (*Node, error)
	IsAuthorized(fromID NodeID, nType NodeType) bool

	// interfaces for API
	Name() string
	CreateUpdateNodeOnDB(n *Node) error
	CreateUpdateNodeOnTable(n *Node) error
	GetNodeFromDB(id NodeID) (*Node, error)
	DeleteNodeFromDB(n *Node) error
	DeleteNodeFromTable(n *Node) error
	GetBucketEntries() []*Node
	GetReplacements() []*Node

	GetAuthorizedNodes() []*Node
	PutAuthorizedNodes(nodes []*Node)
	DeleteAuthorizedNodes(nodes []*Node)
}

func ListenUDP 

func ListenUDP(cfg *Config) (Discovery, error)

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

func NewDiscovery 

func NewDiscovery(cfg *Config) (Discovery, error)

type DiscoveryType 

type DiscoveryType uint8

type KademliaStorage 

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

type Node 

type Node struct {
	IP    net.IP   // len 4 for IPv4 or 16 for IPv6
	UDP   uint16   // discovery port numbers
	TCP   uint16   // TCP listening port number
	TCPs  []uint16 // TCP listening port number including both main port and subports
	ID    NodeID   // the node's public key
	NType NodeType // the node's type (cn, pn, en, bn)

	// PortOrder is the order of the ports that should be connected in multi-channel.
	PortOrder uint16
	// contains filtered or unexported fields
}

Node represents a host on the network. The 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, tcpSubports []uint16, nType NodeType) *Node

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

Example 
id := MustHexID("1dd9d65c4552b5eb43d5ad55a2ee3f56c6cbc1c64a5c8d659f51fcd51bace24351232b8d7821617d2b29b54b81cdefb9b3e9c37d7fd5f63270bcc9e1a6f6a439")

// Complete nodes contain UDP and TCP endpoints:
n1 := NewNode(id, net.ParseIP("2001:db8:3c4d:15::abcd:ef12"), 52150, 30303, nil, NodeTypeUnknown)
fmt.Println("n1:", n1)
fmt.Println("n1.Incomplete() ->", n1.Incomplete())

// An incomplete node can be created by passing zero values
// for all parameters except id.
n2 := NewNode(id, nil, 0, 0, nil, NodeTypeUnknown)
fmt.Println("n2:", n2)
fmt.Println("n2.Incomplete() ->", n2.Incomplete())

Output:

n1: kni://1dd9d65c4552b5eb43d5ad55a2ee3f56c6cbc1c64a5c8d659f51fcd51bace24351232b8d7821617d2b29b54b81cdefb9b3e9c37d7fd5f63270bcc9e1a6f6a439@[2001:db8:3c4d:15::abcd:ef12]:30303?discport=52150
n1.Incomplete() -> false
n2: kni://1dd9d65c4552b5eb43d5ad55a2ee3f56c6cbc1c64a5c8d659f51fcd51bace24351232b8d7821617d2b29b54b81cdefb9b3e9c37d7fd5f63270bcc9e1a6f6a439
n2.Incomplete() -> true

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 

kni://<hex node id> or 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 examples, the node URL describes a node with IP address 10.3.58.6, TCP listening port 30303 and UDP discovery port 30301. 

kni://<hex node id>@10.3.58.6:30303?&subport=30304&discport=30301[&ntype=cn|pn|en|bn]
enode://<hex node id>@10.3.58.6:30303?discport=30301[&ntype=cn|pn|en|bn]

func (*Node) AddSubport 

func (n *Node) AddSubport(port uint16)

AddSubport adds a new port to TCPs TCPs contains unique ports

func (*Node) CompareNode 

func (n *Node) CompareNode(tn *Node) bool

CompareNode implements the compare the all node field and return its result

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 [NodeIDBits / 8]byte

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

func BytesID 

func BytesID(b []byte) (NodeID, error)

BytesID converts a byte slice 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 MustBytesID 

func MustBytesID(b []byte) NodeID

MustBytesID converts a byte slice to a NodeID. It panics if the byte slice is not a valid NodeID.

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) Bytes 

func (n NodeID) Bytes() []byte

Bytes returns a byte slice representation of the NodeID

func (NodeID) GoString 

func (n NodeID) GoString() string

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

func (NodeID) MarshalText 

func (n NodeID) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface.

func (NodeID) Pubkey 

func (id NodeID) Pubkey() (*ecdsa.PublicKey, error)

Pubkey returns the public key represented by the node ID. It returns an error if the ID is not a point on the curve.

func (NodeID) ShortString 

func (n NodeID) ShortString() string

ShortString returns a shortened 4 digits hex string for logging

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.

func (*NodeID) UnmarshalText 

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

UnmarshalText implements the encoding.TextUnmarshaler interface.

type NodeType 

type NodeType uint8

TODO-Kaia Change private type

func ParseNodeType 

func ParseNodeType(nt string) NodeType

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
}

func (*Table) Bond 

func (tab *Table) Bond(pinged bool, id NodeID, addr *net.UDPAddr, tcpPort uint16, nType NodeType) (*Node, error)

Bond ensures the local node has a bond with the given remote node. It also attempts to insert the node into the table if bonding succeeds. The caller must not hold tab.mutex.

A bond is must be established before sending findnode requests. Both sides must have completed a ping/pong exchange for a bond to exist. The total number of active bonding processes is limited in order to restrain network use.

bond is meant to operate idempotently in that bonding with a remote node which still remembers a previously established bond will work. The remote node will simply not send a ping back, causing waitping to time out.

If pinged is true, the remote node has just pinged us and one half of the process can be skipped.

func (*Table) Close 

func (tab *Table) Close()

Close terminates the network listener and flushes the node database.

func (*Table) CreateUpdateNodeOnDB 

func (tab *Table) CreateUpdateNodeOnDB(n *Node) error

CreateUpdateNodeOnDB inserts - potentially overwriting - a node into the peer database.

func (*Table) CreateUpdateNodeOnTable 

func (tab *Table) CreateUpdateNodeOnTable(n *Node) error

CreateUpdateNodeOnDB inserts - potentially overwriting - a node into the associated storage.

func (*Table) DeleteAuthorizedNodes 

func (tab *Table) DeleteAuthorizedNodes(nodes []*Node)

func (*Table) DeleteNodeFromDB 

func (tab *Table) DeleteNodeFromDB(n *Node) error

DeleteNodeFromDB deletes node which has id in peer database.

func (*Table) DeleteNodeFromTable 

func (tab *Table) DeleteNodeFromTable(n *Node) error

DeleteNodeFromDB deletes node which has id in the associated table.

func (*Table) GetAuthorizedNodes 

func (tab *Table) GetAuthorizedNodes() []*Node

func (*Table) GetBucketEntries 

func (tab *Table) GetBucketEntries() []*Node

GetBucketEntries returns nodes in peer databases.

func (*Table) GetNodeFromDB 

func (tab *Table) GetNodeFromDB(id NodeID) (*Node, error)

GetNodeFromDB returns a node which has id in peer database.

func (*Table) GetNodes 

func (tab *Table) GetNodes(targetNT NodeType, max int) []*Node

func (*Table) GetReplacements 

func (tab *Table) GetReplacements() []*Node

GetBucketEntries returns nodes which place in replacements in peer databases.

func (*Table) HasBond 

func (tab *Table) HasBond(id NodeID) bool

func (*Table) IsAuthorized 

func (tab *Table) IsAuthorized(fromID NodeID, nType NodeType) bool

func (*Table) Lookup 

func (tab *Table) Lookup(targetID NodeID, targetType NodeType) []*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.

func (*Table) Name 

func (tab *Table) Name() string

func (*Table) PutAuthorizedNodes 

func (tab *Table) PutAuthorizedNodes(nodes []*Node)

func (*Table) ReadRandomNodes 

func (tab *Table) ReadRandomNodes(buf []*Node, nType NodeType) (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 (*Table) Resolve 

func (tab *Table) Resolve(targetID NodeID, targetType NodeType) *Node

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

func (*Table) RetrieveNodes 

func (tab *Table) RetrieveNodes(target common.Hash, nType NodeType, nresults int) []*Node

RetrieveNodes returns node list except bootnode. This method is used to make a result of FINDNODE request.

func (*Table) Self 

func (tab *Table) Self() *Node

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.