From 8ac0ae392bd4ac7a8b6febdca4a0f544cd056ba8 Mon Sep 17 00:00:00 2001 From: Robert Raynor <35671663+mooselumph@users.noreply.github.com> Date: Tue, 27 Jun 2023 10:05:15 -0700 Subject: [PATCH] Add comments (#32) --- api/proto/disperser/disperser.proto | 8 ++- api/proto/node/node.proto | 5 ++ core/data.go | 81 +++++++++++++++++++---------- 3 files changed, 66 insertions(+), 28 deletions(-) diff --git a/api/proto/disperser/disperser.proto b/api/proto/disperser/disperser.proto index ce4344bea..c2069d17c 100644 --- a/api/proto/disperser/disperser.proto +++ b/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; diff --git a/api/proto/node/node.proto b/api/proto/node/node.proto index 46588afbd..df1b40d42 100644 --- a/api/proto/node/node.proto +++ b/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; diff --git a/core/data.go b/core/data.go index 51691d20a..1ef0d7419 100644 --- a/core/data.go +++ b/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) {