Add comments (#32)

api/proto/disperser/disperser.proto

@@ -10,20 +10,25 @@ service Disperser {
 
 // Requests and Responses
 
+// DisperseBlobRequest contains the blob data to be dispersed.
 message DisperseBlobRequest {
 	bytes data = 1;
 }
 
-// Disperser generates a key, which it must guarantee to be unique across all blobs within its queue. Rollup must use this key to query the status of the blob.
+// DisperseBlobReply contains a key generated by the disperser, which must be unique across all blobs within its queue. 
+// The rollup must use this key to query the status of the blob. Since commitments have not yet been generated, they cannot be used as a key.
 message DisperseBlobReply {
 	BlobStatus result = 1;
 	bytes key = 2;
 }
 
+// BlobStatusRequest is used to query the status of a blob.
 message BlobStatusRequest {
 	bytes key = 1;
 }
 
+// BlobStatusReply contains the status of the blob, as well as the blob's info which includes information needed to confirm the blob
+// against the EigenDA contracts
 message BlobStatusReply {
 	BlobStatus status = 1;
 	BlobInfo info = 2;
@@ -39,6 +44,7 @@ enum BlobStatus {
 	FAILED = 4;
 }
 
+// BlobInfo contains information needed to confirm the blob against the EigenDA contracts
 message BlobInfo {
 	GlomInfo glom = 1;
 	BatchInfo batch = 2;

api/proto/node/node.proto

@@ -20,11 +20,13 @@ message StoreChunksReply {
 
 // Types
 
+// Glom containst both the header and the chunks for a given glom. 
 message Glom {
 	GlomHeader header = 1;
 	repeated bytes chunks = 2;
 }
 
+// GlomHeader (see core/data.go#GlomHeader)
 message GlomHeader {
 	bytes commitment = 1;
 	bytes length_proof = 2;
@@ -35,16 +37,19 @@ message GlomHeader {
 	SecurityParams security_params = 7;
 }
 
+// SecurityParams (see core/data.go#SecurityParams)
 message SecurityParams {
 	uint32 quorum_id = 1;
 	uint32 adversary_threshold = 2;
 }
 
+// QuorumParams (see core/data.go#QuorumParams)
 message QuorumParams {
 	uint32 quorum_id = 1;
 	uint32 quorum_threshold = 2;
 }
 
+// BatchHeader (see core/data.go#BatchHeader)
 message BatchHeader {
 	bytes batch_root = 1;
 	repeated QuorumParams quorum_params = 2;

core/data.go

@@ -2,7 +2,7 @@ package core
 
 // Commitments
 
-// Commitment is a polynomial commitment
+// Commitment is a polynomial commitment (e.g. a kzg commitment)
 type Commitment interface {
 	Serialize() ([]byte, error)
 	Deserialize([]byte) (Commitment, error)
@@ -14,53 +14,67 @@ type Proof interface {
 	Deserialize([]byte) (Proof, error)
 }
 
-// Blob
+// Security and Quorum Paramaters
 
-// QuorumParams contains the security thresholds of a quorum as well as an ID linking the quorum to a smart contract quorum registry.
+// QuorumID is a unique identifier for a quorum; initially EigenDA wil support upt to 256 quorums
 type QuorumID uint8
 
+// SecurityParam contains the quorum ID and the adversary threshold for the quorum;
 type SecurityParam struct {
-	QuorumID           QuorumID
+	QuorumID QuorumID
+	// AdversaryThreshold is the maximum amount of stake that can be controlled by an adversary in the quorum as a percentage of the total stake in the quorum
 	AdversaryThreshold uint8
 }
 
+// QuorumParam contains the quorum ID and the quorum threshold for the quorum
 type QuorumParam struct {
-	QuorumID        QuorumID
+	QuorumID QuorumID
+	// QuorumThreshold is the amount of stake that must sign a message for it to be considered valid as a percentage of the total stake in the quorum
 	QuorumThreshold uint8
 }
 
-// Blob stores the data and header of a single data blob
+// Blob stores the data and header of a single data blob. Blobs are the fundamental unit of data posted to EigenDA by users.
 type Blob struct {
 	Header BlobHeader
 	Data   []byte
 }
 
-// BlobHeader contains the orignal data size of a blob (number of bytes) and the quorums responsible for securing the blob
+// BlobHeader contains the orignal data size of a blob and the security requi
 type BlobHeader struct {
-	BlobSize       uint32
+	// BlobSize is the size of the original data in bytes
+	BlobSize uint32
+	// For a blob to be accepted by EigenDA, it satisfy the AdversaryThreshold of each quorum contained in SecurityParams
 	SecurityParams []SecurityParam
 }
 
 // Glom
+// A glom is a conGLOMeration of blobs. Encoding libraries operate on gloms rather than directly on blobs.
 
-// GlomCommitments contains the glom's commitment, degree proof, and the actual degree. TODO: Determine if this should be abstracted further.
+// GlomHeader contains all of the global information that DA nodes must certify with respect to a glom
+type GlomHeader struct {
+	// Commitment is the polynomial commitment to the glom's data
+	Commitment Commitment
+	// LengthProof is the polynomial commitment to the glom's length; this is used to verify the length of the glom without having to download the entire glom
+	LengthProof Commitment
+	// Length is the length of the glom in symbols; the size of a symbol is determined by the encoding scheme
+	Length uint
+	// ChunkLength is the length of each chunk in symbols; all chunks in an encoded glom must be the same length
+	ChunkLength uint
+	// QuantizationFactor determines the nominal number of chunks; NominalNumChunks = QuantizationFactor * NumOperatorsForQuorum
+	QuantizationFactor uint
+	// NumBlobs is the number of blobs contained the glom
+	NumBlobs uint
+	// SecurityParams specifies the security requirement that the glom must satisfy
+	SecurityParam
+}
+
+// GlomCommitments contains the glom's commitment, degree proof, and the actual degree.
 type GlomCommitments struct {
 	Commitment  Commitment
 	LengthProof Commitment
 	Length      uint
 }
 
-// GlomHeader contains all of the global information that DA nodes must certify.
-type GlomHeader struct {
-	Commitment         Commitment
-	LengthProof        Commitment
-	Length             uint
-	ChunkLength        uint
-	QuantizationFactor uint
-	NumBlobs           uint
-	SecurityParam
-}
-
 // Commitments derives a GlomCommitments object from a GlomHeader
 func (h GlomHeader) Commitments() GlomCommitments {
 	return GlomCommitments{
@@ -71,13 +85,19 @@ func (h GlomHeader) Commitments() GlomCommitments {
 }
 
 // Batch
+// A batch is a collection of gloms. DA nodes receive and attest to the gloms in a batch together to amortize signature verification costs
 
-// HeaderBatch contains the headers associated with a Batch
+// HeaderBatch contains the metadata associated with a Batch for which DA nodes must attest; DA nodes sign on the hash of the batch header
 type BatchHeader struct {
-	GlomHeaders          []GlomHeader
-	QuorumParams         []QuorumParam
+	// GlomHeaders contains the headers of the gloms in the batch
+	GlomHeaders []GlomHeader
+	// QuorumParams contains the quorum parameters for each quorum that must sign the batch; all quorum parameters must be satisfied
+	// for the batch to be considered valid
+	QuorumParams []QuorumParam
+	// ReferenceBlockNumber is the block number at which all operator information (stakes, indexes, etc.) is taken from
 	ReferenceBlockNumber uint
-	BatchRoot            [32]byte
+	// BatchRoot is the root of a Merkle tree whose leaves are the hashes of the gloms in the batch
+	BatchRoot [32]byte
 }
 
 // Batch is a container for a batch of Gloms. DA nodes receive and attest to the gloms in a batch together to amortize signature verification costs
@@ -89,18 +109,25 @@ type EncodedBatch struct {
 
 // Chunk is the smallest unit that is distributed to DA nodes, including both data and the associated polynomial opening proofs.
 type Chunk interface {
+	// Length is the length of the chunk in symbols
 	Length() int
 	Serialize() ([]byte, error)
 	Deserialize([]byte) (Chunk, error)
+	// todo(mooselumph): Add a method for getting the chunk data corresponding to a particular blob index
 }
 
-// ChunkData is a container for the data of a chunk; ChunkData has a representation that depends on the commitment scheme being used.
-
-// ChunkBatch is the collection of chunks associated with a single Batch
+// ChunkBatch is the collection of chunks associated with a single operator and a single batch.
 type ChunkBatch struct {
+	// Bundles contains the chunks associated with each glom in the batch; each bundle contains the chunks associated with a single glom
+	// The number of bundles should be equal to the total number of gloms in the batch. The number of chunks per bundle will vary
 	Bundles [][]Chunk
 }
 
+// EncodedBatch contains all of the ChunkBatches to be distributed to DA nodes
+type Batch struct {
+	ChunkBatches []ChunkBatch
+}
+
 // EncodeChunkBatch encodes a ChunkBatch into a byte array
 func (cb ChunkBatch) Serialize() ([][][]byte, error) {