addrmgr

Documentation

Overview

Package addrmgr implements a concurrently-safe Bitcoin address manager.

Address Manager Overview

In order maintain the peer-to-peer Bitcoin network, there needs to be a source of addresses to connect to as nodes come and go. The Bitcoin protocol provides the getaddr and addr messages to allow peers to communicate known addresses with each other. However, there needs to a mechanism to store those results and select peers from them. It is also important to note that remote peers can't be trusted to send valid peers nor attempt to provide you with only peers they control with malicious intent.

With that in mind, this package provides a concurrency safe address manager for caching and selecting peers in a non-deterministic manner. The general idea is the caller adds addresses to the address manager and notifies it when addresses are connected, known good, and attempted. The caller also requests addresses as it needs them.

The address manager internally segregates the addresses into groups and non-deterministically selects groups in a cryptographically random manner.

This reduces the chances multiple addresses from the same nets are selected which generally helps provide greater peer diversity, and perhaps more importantly, drastically reduces the chances an attacker is able to coerce your peer into only connecting to nodes they control.

The address manager also understands reachability and tries hard to only return globally routeable addresses. In addition, it uses the information provided by the caller about connected, known good, and attempted addresses to periodically purge peers which no longer appear to be good peers as well as bias the selection toward known good peers.

The general idea is to make a best effort at only providing usable addresses.

Index

• type AddrManager
  • func New(dataDir string, lookupFunc func(string) ([]net.IP, er.R)) *AddrManager
  • func (a *AddrManager) AddAddress(addr, srcAddr *wire.NetAddress)
  • func (a *AddrManager) AddAddressByIP(addrIP string) er.R
  • func (a *AddrManager) AddAddresses(addrs []*wire.NetAddress, srcAddr *wire.NetAddress)
  • func (a *AddrManager) AddressesToShare() []*wire.NetAddress
  • func (a *AddrManager) Connected(addr *wire.NetAddress)
  • func (a *AddrManager) DeserializeNetAddress(addr string, services protocol.ServiceFlag) (*wire.NetAddress, er.R)
  • func (a *AddrManager) GetAddress(relaxedMode bool, isOk func(*KnownAddress) bool) *KnownAddress
  • func (a *AddrManager) GetLastAttempt(addr *wire.NetAddress) time.Time
  • func (a *AddrManager) Good(addr *wire.NetAddress)
  • func (a *AddrManager) HostToNetAddress(host string, port uint16, services protocol.ServiceFlag) (*wire.NetAddress, er.R)
  • func (a *AddrManager) NeedMoreAddresses() bool
  • func (a *AddrManager) NumAddresses() int
  • func (a *AddrManager) SetServices(addr *wire.NetAddress, services protocol.ServiceFlag)
  • func (a *AddrManager) Start()
  • func (a *AddrManager) Stop() er.R
• type KnownAddress
  • func (ka *KnownAddress) LastAttempt() time.Time
  • func (ka *KnownAddress) NetAddress() *wire.NetAddress
  • func (ka *KnownAddress) Services() protocol.ServiceFlag

Types

type AddrManager

type AddrManager struct {
	LocalExternal externaladdrs.ExternalLocalAddrs
	// contains filtered or unexported fields
}

AddrManager provides a concurrency safe address manager for caching potential peers on the bitcoin network.

func New

func New(dataDir string, lookupFunc func(string) ([]net.IP, er.R)) *AddrManager

New returns a new bitcoin address manager. Use Start to begin processing asynchronous address updates.

func (*AddrManager) AddAddress

func (a *AddrManager) AddAddress(addr, srcAddr *wire.NetAddress)

AddAddress adds a new address to the address manager. It enforces a max number of addresses and silently ignores duplicate addresses. It is safe for concurrent access.

func (*AddrManager) AddAddressByIP

func (a *AddrManager) AddAddressByIP(addrIP string) er.R

AddAddressByIP adds an address where we are given an ip:port and not a wire.NetAddress.

func (*AddrManager) AddAddresses

func (a *AddrManager) AddAddresses(addrs []*wire.NetAddress, srcAddr *wire.NetAddress)

AddAddresses adds new addresses to the address manager. It enforces a max number of addresses and silently ignores duplicate addresses. It is safe for concurrent access.

func (*AddrManager) AddressesToShare

func (a *AddrManager) AddressesToShare() []*wire.NetAddress

AddressCache returns the current address cache. It must be treated as read-only (but since it is a copy now, this is not as dangerous).

func (*AddrManager) Connected

func (a *AddrManager) Connected(addr *wire.NetAddress)

Connected Marks the given address as currently connected and working at the current time. The address must already be known to AddrManager else it will be ignored.

func (*AddrManager) DeserializeNetAddress

func (a *AddrManager) DeserializeNetAddress(addr string,
	services protocol.ServiceFlag) (*wire.NetAddress, er.R)

DeserializeNetAddress converts a given address string to a *wire.NetAddress.

func (*AddrManager) GetAddress

func (a *AddrManager) GetAddress(relaxedMode bool, isOk func(*KnownAddress) bool) *KnownAddress

GetAddress returns a single address that should be routable. It picks a random one from the possible addresses with preference given to ones that have not been used recently and should not pick 'close' addresses consecutively.

func (*AddrManager) GetLastAttempt

func (a *AddrManager) GetLastAttempt(addr *wire.NetAddress) time.Time

GetLastAttempt retrieves an address' last attempt time.

func (*AddrManager) Good

func (a *AddrManager) Good(addr *wire.NetAddress)

Good marks the given address as good. To be called after a successful connection and version exchange. If the address is unknown to the address manager it will be ignored.

func (*AddrManager) HostToNetAddress

func (a *AddrManager) HostToNetAddress(host string, port uint16, services protocol.ServiceFlag) (*wire.NetAddress, er.R)

HostToNetAddress returns a netaddress given a host address. If the host is not an IP address it will be resolved

func (*AddrManager) NeedMoreAddresses

func (a *AddrManager) NeedMoreAddresses() bool

NeedMoreAddresses returns whether or not the address manager needs more addresses.

func (*AddrManager) NumAddresses

func (a *AddrManager) NumAddresses() int

NumAddresses returns the number of addresses known to the address manager.

func (*AddrManager) SetServices

func (a *AddrManager) SetServices(addr *wire.NetAddress, services protocol.ServiceFlag)

SetServices sets the services for the giiven address to the provided value.

func (*AddrManager) Start

func (a *AddrManager) Start()

Start begins the core address handler which manages a pool of known addresses, timeouts, and interval based writes.

func (*AddrManager) Stop

func (a *AddrManager) Stop() er.R

Stop gracefully shuts down the address manager by stopping the main handler.

type KnownAddress

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

KnownAddress tracks information about a known network address that is used to determine how viable an address is.

func (*KnownAddress) LastAttempt

func (ka *KnownAddress) LastAttempt() time.Time

LastAttempt returns the last time the known address was attempted.

func (*KnownAddress) NetAddress

func (ka *KnownAddress) NetAddress() *wire.NetAddress

NetAddress returns the underlying wire.NetAddress associated with the known address.

func (*KnownAddress) Services

func (ka *KnownAddress) Services() protocol.ServiceFlag

Services returns the services supported by the peer with the known address.