peering

package
v1.6.7 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 47 Imported by: 0

README

peering

The node's P2P layer: how transactions reach other nodes and how missing ones are fetched back. Built on libp2p.

The whole external surface used by the rest of the node is four calls — GossipTxBytesToPeers, PullTransactionsFromPeers, and the two callback registrations OnReceiveTxBytes / OnReceivePullTxRequest. Everything else in here is in service of those.

Transport and protocols

libp2p QUIC-v1 over UDP, with no TLS (libp2p.NoSecurity) and no relay (libp2p.DisableRelay).

Three application protocols, each with a name suffix derived from the ledger library hash:

Protocol Carries File
/proxima/gossip/<hash> Transaction broadcast txbytes.go
/proxima/pull/<hash> Transaction request by ID pull.go
/proxima/connectivity/<hash> Peer-connectivity gossip connectivity.go

The hash suffix is a gate, not decoration. Nodes running different ledger versions have no protocol in common, so they cannot talk at all — an upgrade mismatch is a clean partition rather than a stream of mutual validation failures.

Wire format is a hand-written 4-byte big-endian length prefix plus payload (misc.go, readFrame / writeFrame), capped at MaxPayloadSize = 65,531 bytes. That cap is the reason a transaction larger than ~64 KB cannot be gossiped at all.

Each peer holds one long-lived cached stream per protocol. Per-message outbound streams were tried and rejected: multistream-select negotiation costs about one round trip per message, which is fatal to gossip latency on transcontinental links. Write failures redial once and retry rather than tearing the peer down.

Peers

Peers (types.go) tracks all currently connected peers, with preconfigured static peers held separately so they can be re-dialled after they cycle through the blacklist or cool-off lists. A blacklist and a cool-off list, both TTL-bound, keep the node from hammering peers that misbehaved or just went away; an in-progress dial set prevents reentrant dials.

Liveness is libp2p's, not a protocol of ours: a peer is alive when host.Network().Connectedness(id) == network.Connected. The node counts itself connected to the network while at least one peer is alive. There was once a heartbeat protocol carrying liveness, capability flags and a clock sample; it was removed, and the traffic-timestamp proxy that briefly replaced it proved too quiet on a low-load network — two just-restarted nodes with nothing to gossip looked disconnected.

Discovery

Kademlia DHT in dht.ModeAutoServer, bootstrapped from the static peer list, with a rendezvous string derived from the first 8 bytes of the genesis ledger library hash. An autopeering loop runs every 3 seconds, asks for up to 20 peers, filters out those already known, blacklisted, cooling off or being dialled, and dials up to the peering.max_dynamic_peers cap. A dial in flight reserves its slot before it completes, so a tick landing while earlier dials are still connecting cannot start a second full batch. A candidate the node is already connected to without counting it, usually over a connection the DHT keeps, has that connection closed before the dial: a node on an older release admits a peer only when a new connection arrives, and a dial over the existing one would leave a link it never counted.

A connection alone admits no one. A node that comes to us without being dialled (it lists us as a static peer, or found us through the DHT) is admitted as a dynamic peer when it opens a gossip, pull or connectivity stream to us, which a node does only to peers it counts. The DHT keeps connections of its own and never opens one of those streams, so its connections take no slot. Admitting on connection let them take slots on one side only: links that carried nothing in either direction and could fill a small node's slots. Admission is what makes a newcomer hear anything, since gossip and connectivity records go to registered peers only.

A quarter of the max_dynamic_peers slots (rounded down) is kept for peers the node dials; inbound peers may take the rest, so they can never be all of its links. A positive cap below 4 is raised to 4. When the inbound share is full, one existing inbound dynamic peer is churned out to admit the newcomer. Outbound (autopeered) peers are protected: the node chose to dial them, so a stream of fresh inbound identities cannot replace them. Among inbound peers the least active goes first. Activity is measured on transactions that parsed and passed the signature check plus pull requests, not on raw gossip frames: a peer on an incompatible transaction version cannot look active by flooding transactions that are refused at parsing. Churn is limited to one eviction per minute, and a peer admitted within the grace period (2 min) is never the victim, so a newcomer cannot displace the peer it just replaced. A peer that was evicted for churn, the newcomer that caused the eviction, and a peer that disappeared within 5 s of admission are all barred from triggering another churn; the first two for 10 minutes, the last for 1 hour. Either way an inbound connection is still admitted when a slot is free, but autopeering does not redial the peer until the cooldown expires, and it cannot evict a working peer on its next redial. Without that bar a small set of redialling peers keeps the set rotating, and a peer that connects and immediately vanishes (for example one on another ledger that closes before the protocol check) keeps displacing healthy peers. A peer that keeps sending transactions from another version is dropped after 10 mismatches in a minute and receives the same 1-hour cooldown. If every inbound peer is still inside its grace period, no inbound victim exists, or the newcomer is in churn cooldown, its stream is reset and the connection is kept: the newcomer keeps its discovery DHT through us and finds peers with free slots elsewhere. The connection manager's high watermark (static + cap + 5) remains as a backstop.

Gossip, pull requests and connectivity records are accepted only from a registered peer, from one admitted by that stream, or from one whose outbound dial is still in flight. A connection alone does not admit a peer, so gossip over a DHT connection never bypasses max_dynamic_peers.

A dynamic peer that has sent nothing within a minute of being added, or nothing for 5 minutes since its last message, is dropped, with the usual 10-minute cooldown. A peer that counts us starts relaying within seconds, sends connectivity records every 15 s and relays every slot's sequencer transactions, so that silence means the other side does not count us: it refused our streams or never admitted us, and the link would otherwise hold a slot on our side forever. The 5-minute margin covers a peer that sends no connectivity records while the network is quiet. Static peers are never dropped.

A refused stream is reset, and the sender only finds out on its next write, so without a limit it would open a new stream for every message. A stream to one peer and protocol reopened more than 3 times within 10 s is paused instead: 1 s at first, doubling while the refusals go on, up to 30 s, and back to no pause after a quiet 10 s. Messages in a pause are dropped and counted (proxima_peering_outMsgPaused); the refusing side counts what it refused (proxima_peering_streamsRefused). This is what a node sees when a static peer of its own does not count it back.

Autopeering is off when max_dynamic_peers is at or below zero, in which case the node accepts no incoming dynamic peers either.

Configuration

Key Effect
peering.host.port UDP port
peering.peers Preconfigured (static) peers, also the DHT bootstrap set
peering.max_dynamic_peers Cap on dynamic peers (static peers do not count); ≤ 0 disables autopeering and refuses all inbound dynamic peers
peering.ignore_all_pull_requests Serve no pull requests at all
peering.accept_pull_requests_from_static_peers_only Serve pulls only to static peers

Also here

Documentation

Index

Constants

View Source
const BeginPort = 4000
View Source
const (
	MaxPayloadSize = math.MaxUint16 - 4
)

MaxPayloadSize caps the message size. It includes 4 bytes of the size

View Source
const Name = "peers"
View Source
const PullTransactions = byte(iota)

Variables

This section is empty.

Functions

func MultiAddrString

func MultiAddrString(i int, port int) string

func ShortPeerIDString

func ShortPeerIDString(id peer.ID) string

Types

type AddressFilter

type AddressFilter = func([]multiaddr.Multiaddr) []multiaddr.Multiaddr

func FilterAddresses

func FilterAddresses(allowLocalNetworks bool, hostPort int, externalIPs []net.IP) AddressFilter

FilterAddresses builds the host's advertised address set (libp2p AddrsFactory). On top of whatever libp2p discovered, the node advertises itself at hostPort on:

  • every local network interface IP, and
  • every operator-declared external IP (peering.host.external_addresses).

The union is deduplicated and reduced to public addresses only (unless allowLocalNetworks). The interface IPs cover the common case where the public IP is bound to the host's NIC; declared external IPs cover NAT/port-mapping, where the public IP is on no local interface and cannot be auto-detected.

type Config

type Config struct {
	HostIDPrivateKey ed25519.PrivateKey
	HostID           peer.ID
	HostPort         int
	// HostExternalIPs are operator-declared public IPs the node advertises itself
	// at (peering.host.external_addresses), at HostPort. Needed when the node is
	// reachable through NAT/port mapping and its public IP is on no local interface,
	// so neither interface enumeration nor observed-address discovery can find it.
	HostExternalIPs    []net.IP
	PreConfiguredPeers map[string]_multiaddr // name -> PeerAddr. Static peers used also for bootstrap
	// MaxDynamicPeers is the maximum number of dynamic peers, whether dialled
	// by autopeering or admitted when they opened a stream to us. Zero disables
	// autopeering, in which case no dynamic peer is admitted either; a positive
	// value below minDynamicPeers is raised to it. A quarter of the slots is kept
	// for peers this node dials. When the slots peers may take are full, an
	// inbound newcomer churns one existing inbound peer rather than being locked
	// out; outbound peers are protected (see _makeRoomForInboundPeerLocked).
	MaxDynamicPeers int
	// Node info
	IgnoreAllPullRequests                 bool
	AcceptPullRequestsFromStaticPeersOnly bool
	// AllowLocalIPs defines if local IPs are allowed to be used for autopeering.
	AllowLocalIPs bool `default:"false" usage:"allow local IPs to be used for autopeering"`

	// disable Quicreuse
	DisableQuicreuse bool

	// ConnectivityDisabled disables the lppConnectivity network-mapping overlay
	// (peering.connectivity.disable). Default false (= enabled).
	ConnectivityDisabled bool
}

func MakeConfigFor

func MakeConfigFor(n, hostIdx int) *Config

type Peer

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

type PeerConnections added in v1.1.1

type PeerConnections struct {
	Name                  string            `json:"name"`                            // origin masked name, 16-hex
	ConsensusContribution uint64            `json:"consensusContribution,omitempty"` // sequencer mass; 0/omitted for access nodes
	ByPeer                map[string]uint64 `json:"byPeer"`                          // peer masked name (16-hex) -> RTT microseconds
	Timestamp             int64             `json:"timestamp"`                       // unix nanos at origin
	Seq                   uint64            `json:"seq"`                             // origin-monotone sequence number
}

PeerConnections is one node's local connectivity view, gossiped verbatim.

type Peers

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

func New

func New(env environment, cfg *Config) (*Peers, error)

func NewPeersDummy

func NewPeersDummy() *Peers

func NewPeersDummyGossiping added in v1.6.4

func NewPeersDummyGossiping(fun func(txBytes []byte, txid base.TransactionID)) *Peers

NewPeersDummyGossiping is a dummy which hands every gossiped transaction to fun

func NewPeersFromConfig

func NewPeersFromConfig(env environment) (*Peers, error)

func (*Peers) DurationSinceLastMessageFromPeer

func (ps *Peers) DurationSinceLastMessageFromPeer() time.Duration

DurationSinceLastMessageFromPeer is the silence since the last incoming gossip, pull or connectivity message; before Run it is 0.

func (*Peers) EvidenceInvalidTx added in v1.5.2

func (ps *Peers) EvidenceInvalidTx(id peer.ID)

EvidenceInvalidTx records a transaction refused at parsing because its version does not match this node's library, or refused at the signature check. One is tolerated; after invalidTxLimit within invalidTxWindow the peer is on an incompatible version or is sending forged copies, so it is dropped and barred from churning for the flap cooldown.

func (*Peers) EvidenceValidTx added in v1.3.6

func (ps *Peers) EvidenceValidTx(id peer.ID)

EvidenceValidTx records a peer transaction that parsed and passed the signature check. Churn activity is measured on this, not on raw gossip frames, so a peer sending an incompatible transaction version cannot look active by flooding transactions that are refused before validation.

func (*Peers) GetConnectivityMap added in v1.1.1

func (ps *Peers) GetConnectivityMap() *api.ConnectivityMap

GetConnectivityMap returns the whole stored connectivity map for the API.

func (*Peers) GetConnectivityMatrix added in v1.1.1

func (ps *Peers) GetConnectivityMatrix() *api.ConnectivityMatrix

GetConnectivityMatrix returns the symmetric pairwise distance metric d(i,j) derived from the connectivity map. The result is cached and lazily recomputed at most once per connMatrixRefreshInterval (the matrix is expensive for large N).

func (*Peers) GetPeersInfo

func (ps *Peers) GetPeersInfo() *api.PeersInfo

func (*Peers) GossipTxBytesToPeers

func (ps *Peers) GossipTxBytesToPeers(txBytes []byte, txid base.TransactionID, except ...peer.ID)

func (*Peers) Host

func (ps *Peers) Host() host.Host

func (*Peers) IsAlive

func (ps *Peers) IsAlive(id peer.ID) (isAlive bool)

func (*Peers) IsConnectedToNetwork added in v1.1.1

func (ps *Peers) IsConnectedToNetwork() bool

IsConnectedToNetwork returns true if libp2p reports at least one peer currently connected. After the heartbeat protocol was removed, this is the authoritative "node has a working connection to the network" signal — the previous traffic-timestamp proxy is too quiet on low-load networks (e.g. a pair of just-restarted nodes with no transactions to gossip).

func (*Peers) NewStream

func (ps *Peers) NewStream(peerID peer.ID, pID protocol.ID, timeout time.Duration) (network.Stream, error)

func (*Peers) NumAlive

func (ps *Peers) NumAlive() (aliveStatic, aliveDynamic int)

NumAlive returns counts of alive static / dynamic peers and pull targets. "Alive" is libp2p-Connectedness-driven (see _isAlive).

func (*Peers) OnReceivePullTxRequest

func (ps *Peers) OnReceivePullTxRequest(fun func(from peer.ID, txid base.TransactionID))

func (*Peers) OnReceiveTxBytes

func (ps *Peers) OnReceiveTxBytes(fun func(from peer.ID, txBytes []byte, txIDPrefix base.TransactionID))

func (*Peers) PeerName

func (ps *Peers) PeerName(id peer.ID) string

func (*Peers) PullTransactionsFromPeers

func (ps *Peers) PullTransactionsFromPeers(txid base.TransactionID) int

PullTransactionsFromPeers sends pull request to all peers that respond to pull requests

func (*Peers) Run

func (ps *Peers) Run()

func (*Peers) SelfPeerID

func (ps *Peers) SelfPeerID() peer.ID

func (*Peers) SendTxBytesToPeer added in v1.1.1

func (ps *Peers) SendTxBytesToPeer(id peer.ID, txBytes []byte, txid base.TransactionID) bool

func (*Peers) Stop

func (ps *Peers) Stop()

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址