github.com/celestiaorg/celestia-node@v0.15.0-beta.1/share/p2p/peers/doc.go (about)

     1  // Package peers provides a peer manager that handles peer discovery and peer selection for the shrex getter.
     2  //
     3  // The peer manager is responsible for:
     4  //   - Discovering peers
     5  //   - Selecting peers for data retrieval
     6  //   - Validating peers
     7  //   - Blacklisting peers
     8  //   - Garbage collecting peers
     9  //
    10  // The peer manager is not responsible for:
    11  //   - Connecting to peers
    12  //   - Disconnecting from peers
    13  //   - Sending data to peers
    14  //   - Receiving data from peers
    15  //
    16  // The peer manager is a mechanism to store peers from shrexsub, a mechanism that
    17  // handles "peer discovery" and "peer selection" by relying on a shrexsub subscription
    18  // and header subscriptions, such that it listens for new headers and
    19  // new shares and uses this information to pool peers by shares.
    20  //
    21  // This gives the peer manager an ability to block peers that gossip invalid shares, but also access a list of peers
    22  // that are known to have been gossiping valid shares.
    23  // The peers are then returned on request using a round-robin algorithm to return a different peer each time.
    24  // If no peers are found, the peer manager will rely on full nodes retrieved from discovery.
    25  //
    26  // The peer manager is only concerned with recent heights, thus it retrieves peers that
    27  // were active since `initialHeight`.
    28  // The peer manager will also garbage collect peers such that it blacklists peers that
    29  // have been active since `initialHeight` but have been found to be invalid.
    30  //
    31  // The peer manager is passed to the shrex getter and is used at request time to
    32  // select peers for a given data hash for data retrieval.
    33  //
    34  // # Usage
    35  //
    36  // The peer manager is created using [NewManager] constructor:
    37  //
    38  //	peerManager := peers.NewManager(headerSub, shrexSub, discovery, host, connGater, opts...)
    39  //
    40  // After creating the peer manager, it should be started to kick off listening and
    41  // validation routines that enable peer selection and retrieval:
    42  //
    43  //	err := peerManager.Start(ctx)
    44  //
    45  // The peer manager can be stopped at any time to stop all peer discovery and validation routines:
    46  //
    47  //	err := peerManager.Stop(ctx)
    48  //
    49  // The peer manager can be used to select peers for a given datahash for shares retrieval:
    50  //
    51  //	peer, err := peerManager.Peer(ctx, hash)
    52  package peers