peers

Documentation

Overview

Package peers provides information about peers at the Ethereum protocol level. "Protocol level" is the level above the network level, so this layer never sees or interacts with (for example) hosts that are uncontactable due to being down, firewalled, etc. Instead, this works with peers that are contactable but may or may not be of the correct fork version, not currently required due to the number of current connections, etc.

A peer can have one of a number of states:

- connected if we are able to talk to the remote peer - connecting if we are attempting to be able to talk to the remote peer - disconnecting if we are attempting to stop being able to talk to the remote peer - disconnected if we are not able to talk to the remote peer

For convenience, there are two aggregate states expressed in functions:

- active if we are connecting or connected - inactive if we are disconnecting or disconnected

Peer information is persistent for the run of the service. This allows for collection of useful long-term statistics such as number of bad responses obtained from the peer, giving the basis for decisions to not talk to known-bad peers.

Index

• Variables
• type PeerConnectionState
• type Status
  • func NewStatus(maxBadResponses int) *Status
  • func (p *Status) Active() []peer.ID
  • func (p *Status) Add(pid peer.ID, address ma.Multiaddr, direction network.Direction)
  • func (p *Status) Address(pid peer.ID) (ma.Multiaddr, error)
  • func (p *Status) All() []peer.ID
  • func (p *Status) Bad() []peer.ID
  • func (p *Status) BadResponses(pid peer.ID) (int, error)
  • func (p *Status) BestFinalized(maxPeers int, ourFinalizedEpoch uint64) ([]byte, uint64, []peer.ID)
  • func (p *Status) ChainState(pid peer.ID) (*pb.Status, error)
  • func (p *Status) ChainStateLastUpdated(pid peer.ID) (time.Time, error)
  • func (p *Status) Connected() []peer.ID
  • func (p *Status) Connecting() []peer.ID
  • func (p *Status) ConnectionState(pid peer.ID) (PeerConnectionState, error)
  • func (p *Status) CurrentEpoch() uint64
  • func (p *Status) Decay()
  • func (p *Status) Direction(pid peer.ID) (network.Direction, error)
  • func (p *Status) Disconnected() []peer.ID
  • func (p *Status) Disconnecting() []peer.ID
  • func (p *Status) Inactive() []peer.ID
  • func (p *Status) IncrementBadResponses(pid peer.ID)
  • func (p *Status) IsBad(pid peer.ID) bool
  • func (p *Status) MaxBadResponses() int
  • func (p *Status) SetChainState(pid peer.ID, chainState *pb.Status)
  • func (p *Status) SetConnectionState(pid peer.ID, state PeerConnectionState)

Variables

var (
	// ErrPeerUnknown is returned when there is an attempt to obtain data from a peer that is not known.
	ErrPeerUnknown = errors.New("peer unknown")
)

Types

type PeerConnectionState

type PeerConnectionState int

PeerConnectionState is the state of the connection.

const (
	// PeerDisconnected means there is no connection to the peer.
	PeerDisconnected PeerConnectionState = iota
	// PeerConnecting means there is an on-going attempt to connect to the peer.
	PeerConnecting
	// PeerConnected means the peer has an active connection.
	PeerConnected
	// PeerDisconnecting means there is an on-going attempt to disconnect from the peer.
	PeerDisconnecting
)

type Status

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

Status is the structure holding the peer status information.

func NewStatus

func NewStatus(maxBadResponses int) *Status

NewStatus creates a new status entity.

func (*Status) Active

func (p *Status) Active() []peer.ID

Active returns the peers that are connecting or connected.

func (*Status) Add

func (p *Status) Add(pid peer.ID, address ma.Multiaddr, direction network.Direction)

Add adds a peer. If a peer already exists with this ID its address and direction are updated with the supplied data.

func (*Status) Address

func (p *Status) Address(pid peer.ID) (ma.Multiaddr, error)

Address returns the multiaddress of the given remote peer. This will error if the peer does not exist.

func (*Status) All

func (p *Status) All() []peer.ID

All returns all the peers regardless of state.

func (*Status) Bad

func (p *Status) Bad() []peer.ID

Bad returns the peers that are bad.

func (*Status) BadResponses

func (p *Status) BadResponses(pid peer.ID) (int, error)

BadResponses obtains the number of bad responses we have received from the given remote peer. This will error if the peer does not exist.

func (*Status) BestFinalized

func (p *Status) BestFinalized(maxPeers int, ourFinalizedEpoch uint64) ([]byte, uint64, []peer.ID)

BestFinalized returns the highest finalized epoch equal to or higher than ours that is agreed upon by the majority of peers. This method may not return the absolute highest finalized, but the finalized epoch in which most peers can serve blocks. Ideally, all peers would be reporting the same finalized epoch but some may be behind due to their own latency, or because of their finalized epoch at the time we queried them. Returns the best finalized root, epoch number, and list of peers that are at or beyond that epoch.

func (*Status) ChainState

func (p *Status) ChainState(pid peer.ID) (*pb.Status, error)

ChainState gets the chain state of the given remote peer. This can return nil if there is no known chain state for the peer. This will error if the peer does not exist.

func (*Status) ChainStateLastUpdated

func (p *Status) ChainStateLastUpdated(pid peer.ID) (time.Time, error)

ChainStateLastUpdated gets the last time the chain state of the given remote peer was updated. This will error if the peer does not exist.

func (*Status) Connected

func (p *Status) Connected() []peer.ID

Connected returns the peers that are connected.

func (*Status) Connecting

func (p *Status) Connecting() []peer.ID

Connecting returns the peers that are connecting.

func (*Status) ConnectionState

func (p *Status) ConnectionState(pid peer.ID) (PeerConnectionState, error)

ConnectionState gets the connection state of the given remote peer. This will error if the peer does not exist.

func (*Status) CurrentEpoch

func (p *Status) CurrentEpoch() uint64

CurrentEpoch returns the highest reported epoch amongst peers.

func (*Status) Decay

func (p *Status) Decay()

Decay reduces the bad responses of all peers, giving reformed peers a chance to join the network. This can be run periodically, although note that each time it runs it does give all bad peers another chance as well to clog up the network with bad responses, so should not be run too frequently; once an hour would be reasonable.

func (*Status) Direction

func (p *Status) Direction(pid peer.ID) (network.Direction, error)

Direction returns the direction of the given remote peer. This will error if the peer does not exist.

func (*Status) Disconnected

func (p *Status) Disconnected() []peer.ID

Disconnected returns the peers that are disconnected.

func (*Status) Disconnecting

func (p *Status) Disconnecting() []peer.ID

Disconnecting returns the peers that are disconnecting.

func (*Status) Inactive

func (p *Status) Inactive() []peer.ID

Inactive returns the peers that are disconnecting or disconnected.

func (*Status) IncrementBadResponses

func (p *Status) IncrementBadResponses(pid peer.ID)

IncrementBadResponses increments the number of bad responses we have received from the given remote peer.

func (*Status) IsBad

func (p *Status) IsBad(pid peer.ID) bool

IsBad states if the peer is to be considered bad. If the peer is unknown this will return `false`, which makes using this function easier than returning an error.

func (*Status) MaxBadResponses

func (p *Status) MaxBadResponses() int

MaxBadResponses returns the maximum number of bad responses a peer can provide before it is considered bad.

func (*Status) SetChainState

func (p *Status) SetChainState(pid peer.ID, chainState *pb.Status)

SetChainState sets the chain state of the given remote peer.

func (*Status) SetConnectionState

func (p *Status) SetConnectionState(pid peer.ID, state PeerConnectionState)

SetConnectionState sets the connection state of the given remote peer.