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

     1  // This package defines a protocol that is used to request
     2  // extended data squares from peers in the network.
     3  //
     4  // This protocol is a request/response protocol that allows for sending requests for extended data squares by data root
     5  // to the peers in the network and receiving a response containing the original data square(s), which is used
     6  // to recompute the extended data square.
     7  //
     8  // The streams are established using the protocol ID:
     9  //
    10  //   - "{networkID}/shrex/eds/v0.0.1" where networkID is the network ID of the network. (e.g. "arabica")
    11  //
    12  // When a peer receives a request for extended data squares, it will read
    13  // the original data square from the EDS store by retrieving the underlying
    14  // CARv1 file containing the full extended data square, but will limit reading
    15  // to the original data square shares only.
    16  // The client on the other hand will take care of computing the extended data squares from
    17  // the original data square on receipt.
    18  //
    19  // # Usage
    20  //
    21  // To use a shrexeds client to request extended data squares from a peer, you must
    22  // first create a new `shrexeds.Client` instance by:
    23  //
    24  //	client, err := shrexeds.NewClient(params, host)
    25  //
    26  // where `params` is a `shrexeds.Parameters` instance and `host` is a `libp2p.Host` instance.
    27  //
    28  // To request extended data squares from a peer, you must first create a `Client.RequestEDS` instance by:
    29  //
    30  //	eds, err := client.RequestEDS(ctx, dataHash, peer)
    31  //
    32  // where:
    33  //   - `ctx` is a `context.Context` instance,
    34  //   - `dataHash` is the data root of the extended data square and
    35  //   - `peer` is the peer ID of the peer to request the extended data square from.
    36  //
    37  // To use a shrexeds server to respond to requests for extended data squares from peers
    38  // you must first create a new `shrexeds.Server` instance by:
    39  //
    40  //	server, err := shrexeds.NewServer(params, host, store)
    41  //
    42  // where `params` is a [Parameters] instance, `host` is a libp2p.Host instance and `store` is a [eds.Store] instance.
    43  //
    44  // To start the server, you must call `Start` on the server:
    45  //
    46  //	err := server.Start(ctx)
    47  //
    48  // To stop the server, you must call `Stop` on the server:
    49  //
    50  //	err := server.Stop(ctx)
    51  package shrexeds