Lux P2P Networking

type Config struct {
    HealthConfig         // Health check parameters
    PeerListGossipConfig // Peer list gossip settings
    TimeoutConfig        // Ping/pong, handshake timeouts
    DelayConfig          // Reconnect delay (exponential backoff)
    ThrottlerConfig      // Inbound/outbound message throttling

    ProxyEnabled           bool          // PROXY protocol support
    ProxyReadHeaderTimeout time.Duration

    MyNodeID           ids.NodeID
    MyIPPort           *utils.Atomic[netip.AddrPort]
    NetworkID          uint32
    MaxClockDifference time.Duration
    PingFrequency      time.Duration
    AllowPrivateIPs    bool

    SupportedLPs set.Set[uint32]  // LP proposals this node supports
    ObjectedLPs  set.Set[uint32]  // LP proposals this node objects to

    CompressionType compression.Type
    TLSKey          crypto.Signer
    BLSKey          bls.Signer

    TrackedChains set.Set[ids.ID]
    Beacons       validators.Manager
    Validators    validators.Manager

    // SequencerIDForChain returns the validator-set identity that sequences chainID
    // Examples: C-Chain -> PrimaryNetworkID, Zoo L2 -> ZooChainID
    SequencerIDForChain func(chainID ids.ID) ids.ID

    GenesisBytes         []byte
    UptimeCalculator     uptime.Calculator
    UptimeMetricFreq     time.Duration
    UptimeRequirement    float64
    RequireValidatorToConnect bool

    MaximumInboundMessageTimeout time.Duration
    PeerReadBufferSize           int
    PeerWriteBufferSize          int

    ResourceTracker consensustracker.ResourceTracker
    CPUTargeter     tracker.Targeter
    DiskTargeter    tracker.Targeter
}

type HealthConfig struct {
    Enabled                                bool
    NoIngressValidatorConnectionGracePeriod time.Duration
    MinConnectedPeers                      uint          // Minimum peers for healthy
    MaxTimeSinceMsgReceived                time.Duration // Max silence before unhealthy
    MaxTimeSinceMsgSent                    time.Duration
    MaxPortionSendQueueBytesFull           float64       // (0,1]
    MaxSendFailRate                        float64       // [0,1]
    SendFailRateHalflife                   time.Duration
}

type PeerListGossipConfig struct {
    PeerListNumValidatorIPs uint32        // Validator IPs per gossip round
    PeerListPullGossipFreq  time.Duration // How often to request IPs
    PeerListBloomResetFreq  time.Duration // Bloom filter recalculation interval
}

github.com/luxfi/p2p/
  network.go       Network (top-level coordinator), Peers, PeerSampler, ClientOption
  handler.go       Handler interface (Gossip/Request), NoOpHandler, ValidatorHandler, responder
  router.go        router (message dispatch by handlerID), ParseMessage, metrics
  client.go        Client (RequestAny, Request, Gossip), ResponseCallback, PrefixMessage
  sender.go        Sender interface (SendRequest/SendResponse/SendError/SendGossip), SendConfig
  error.go         Error type with codes: ErrUnexpected(-1), ErrUnregisteredHandler(-2),
                   ErrNotValidator(-3), ErrThrottled(-4)
  validators.go    Validators (ValidatorSet/ValidatorSubset/NodeSampler), stake-weighted sampling
  node_sampler.go  NodeSampler interface (Sample)
  peer_tracker.go  PeerTracker (bandwidth-based peer selection), bandwidthHeap, exponential decay
  throttler.go     SlidingWindowThrottler (per-node rate limiting)

  gossip/
    gossipable.go  Gossipable interface (GossipID), Marshaller, Set
    gossip.go      PullGossiper, PushGossiper, ValidatorGossiper, BranchingFactor, Every()
    bloom.go       BloomFilter (probabilistic membership, auto-reset)
    handler.go     Gossip protocol handler
    message.go     MarshalAppRequest/ParseAppResponse/MarshalAppGossip/ParseAppGossip

  throttling/
    bandwidth_throttler.go         Token-bucket bandwidth throttler (rate.Limiter)
    inbound_msg_throttler.go       Composite inbound message throttler
    inbound_msg_byte_throttler.go  Byte-level inbound throttling
    inbound_msg_buffer_throttler.go Buffer-level throttling
    inbound_conn_throttler.go      Connection rate throttling
    inbound_conn_upgrade_throttler.go TLS upgrade throttling
    inbound_resource_throttler.go  Resource-based throttling
    outbound_msg_throttler.go      Outbound message throttling
    dial_throttler.go              Outbound dial throttling

  peer/
    peer.go              Peer connection management (~33KB, largest file)
    config.go            Peer configuration
    set.go               Peer set with thread-safe operations
    info.go              Peer metadata (NodeID, version, IP)
    gossip_tracker.go    Per-peer gossip tracking
    ip.go                Peer IP management
    ip_signer.go         IP signature for peer identity
    tls_config.go        TLS configuration for peer connections
    message_queue.go     Priority message queue per peer
    bounded_queue.go     Bounded queue implementation
    upgrader.go          Connection upgrade (TCP -> TLS)
    validator_id.go      Validator identity

  message/
    ops.go               Message operation types (all consensus + app messages)
    messages.go          Message serialization/deserialization
    inbound_msg_builder.go  Inbound message construction
    outbound_msg_builder.go Outbound message construction
    internal_msg_builder.go Internal message construction
    creator.go           Message creator

  lp118/
    lp118.go          LP-118 signature request protocol
    aggregator.go     Signature aggregation

  tracker/
    resource_tracker.go  CPU/bandwidth resource tracking
    targeter_impl.go     Target selection for throttling

  proto/
    pb/p2p/p2p.pb.go  Protobuf-generated message types

// Create network with metrics
net, err := p2p.NewNetwork(logger, sender, registerer, "myvm")

// Register a handler for a protocol
err = net.AddHandler(p2p.TxGossipHandlerID, myHandler)

// Create a client for sending messages
client := net.NewClient(p2p.TxGossipHandlerID)

// Peer connect/disconnect callbacks (implements validators.Connector)
net.Connected(ctx, nodeID, version)
net.Disconnected(ctx, nodeID)

type Handler interface {
    Gossip(ctx context.Context, nodeID ids.NodeID, gossipBytes []byte)
    Request(ctx context.Context, nodeID ids.NodeID, deadline time.Time, requestBytes []byte) ([]byte, *Error)
}

// Request to a random peer
client.RequestAny(ctx, requestBytes, func(ctx context.Context, nodeID ids.NodeID, response []byte, err error) {
    // handle response
})

// Request to specific peers
client.Request(ctx, nodeIDs, requestBytes, onResponse)

// Gossip to peers
client.Gossip(ctx, p2p.SendConfig{
    Validators:    3,
    NonValidators: 5,
    Peers:         2,
}, gossipBytes)

type Gossipable interface {
    GossipID() ids.ID
}

type Set[T Gossipable] interface {
    Add(T) error
    Has(ids.ID) bool
    Iterate(func(T) bool)
    GetFilter() (bloom []byte, salt []byte)
}