package disperser

Get desktop application:
View/edit binary Protocol Buffers messages

Disperser defines the public APIs for dispersing blobs.

• rpc DisperseBlob (DisperseBlobRequest, DisperseBlobReply)

  disperser.proto:20

  DisperseBlob accepts a single blob to be dispersed. This executes the dispersal async, i.e. it returns once the request is accepted. The client should use GetBlobStatus() API to poll the processing status of the blob. If DisperseBlob returns the following error codes: INVALID_ARGUMENT (400): request is invalid for a reason specified in the error msg. RESOURCE_EXHAUSTED (429): request is rate limited for the quorum specified in the error msg. user should retry after the specified duration. INTERNAL (500): serious error, user should NOT retry.

• rpc DisperseBlobAuthenticated (stream AuthenticatedRequest, stream AuthenticatedReply)

  disperser.proto:30

  DisperseBlobAuthenticated is similar to DisperseBlob, except that it requires the client to authenticate itself via the AuthenticationData message. The protocol is as follows: 1. The client sends a DisperseBlobAuthenticated request with the DisperseBlobRequest message 2. The Disperser sends back a BlobAuthHeader message containing information for the client to verify and sign. 3. The client verifies the BlobAuthHeader and sends back the signed BlobAuthHeader in an AuthenticationData message. 4. The Disperser verifies the signature and returns a DisperseBlobReply message.

  message AuthenticatedRequest

  disperser.proto:48

  • oneof payload

    • DisperseBlobRequest disperse_request = 1

    • AuthenticationData authentication_data = 2

  message AuthenticatedReply

  disperser.proto:55

  • oneof payload

    • BlobAuthHeader blob_auth_header = 1

    • DisperseBlobReply disperse_reply = 2

• rpc GetBlobStatus (BlobStatusRequest, BlobStatusReply)

  disperser.proto:33

  This API is meant to be polled for the blob status.

  message BlobStatusRequest

  disperser.proto:116

  BlobStatusRequest is used to query the status of a blob.

  • bytes request_id = 1

    Refer to the documentation for `DisperseBlobReply.request_id`. Note that because the request_id depends on the timestamp at which the disperser received the request, it is not possible to compute it locally from the cert and blob. Clients should thus store this request_id if they plan on requerying the status of the blob in the future.

  message BlobStatusReply

  disperser.proto:124

  • BlobStatus status = 1

    The status of the blob.

  • optional BlobInfo info = 2

    The blob info needed for clients to confirm the blob against the EigenDA contracts.

• rpc RetrieveBlob (RetrieveBlobRequest, RetrieveBlobReply)

  disperser.proto:41

  This retrieves the requested blob from the Disperser's backend. This is a more efficient way to retrieve blobs than directly retrieving from the DA Nodes (see detail about this approach in api/proto/retriever/retriever.proto). The blob should have been initially dispersed via this Disperser service for this API to work.

  message RetrieveBlobRequest

  disperser.proto:132

  RetrieveBlobRequest contains parameters to retrieve the blob.

  • bytes batch_header_hash = 1

  • uint32 blob_index = 2

  message RetrieveBlobReply

  disperser.proto:138

  RetrieveBlobReply contains the retrieved blob data

  • bytes data = 1

AuthenticationData contains the signature of the BlobAuthHeader.

Used in: AuthenticatedRequest

• bytes authentication_data = 1

Used in: BatchMetadata

• bytes batch_root = 1

  The root of the merkle tree with the hashes of blob headers as leaves.

• bytes quorum_numbers = 2

  All quorums associated with blobs in this batch. Sorted in ascending order. Ex. [0, 2, 1] => 0x000102

• bytes quorum_signed_percentages = 3

  The percentage of stake that has signed for this batch. The quorum_signed_percentages[i] is percentage for the quorum_numbers[i].

• uint32 reference_block_number = 4

  The Ethereum block number at which the batch was created. The Disperser will encode and disperse the blobs based on the onchain info (e.g. operator stakes) at this block number.

Used in: BlobVerificationProof

• optional BatchHeader batch_header = 1

• bytes signatory_record_hash = 2

  The hash of all public keys of the operators that did not sign the batch.

• bytes fee = 3

  The fee payment paid by users for dispersing this batch. It's the bytes representation of a big.Int value.

• uint32 confirmation_block_number = 4

  The Ethereum block number at which the batch is confirmed onchain.

• bytes batch_header_hash = 5

  This is the hash of the ReducedBatchHeader defined onchain, see: https://github.com/Layr-Labs/eigenda/blob/master/contracts/src/interfaces/IEigenDAServiceManager.sol#L43 The is the message that the operators will sign their signatures on.

BlobAuthHeader contains information about the blob for the client to verify and sign. - Once payments are enabled, the BlobAuthHeader will contain the KZG commitment to the blob, which the client will verify and sign. Having the client verify the KZG commitment instead of calculating it avoids the need for the client to have the KZG structured reference string (SRS), which can be large. The signed KZG commitment prevents the disperser from sending a different blob to the DA Nodes than the one the client sent. - In the meantime, the BlobAuthHeader contains a simple challenge parameter is used to prevent replay attacks in the event that a signature is leaked.

Used in: AuthenticatedReply

• uint32 challenge_parameter = 1

Used in: BlobInfo

• optional common.G1Commitment commitment = 1

  KZG commitment of the blob.

• uint32 data_length = 2

  The length of the blob in symbols (each symbol is 32 bytes).

• repeated BlobQuorumParam blob_quorum_params = 3

  The params of the quorums that this blob participates in.

BlobInfo contains information needed to confirm the blob against the EigenDA contracts

Used in: BlobStatusReply

• optional BlobHeader blob_header = 1

• optional BlobVerificationProof blob_verification_proof = 2

Used in: BlobHeader

• uint32 quorum_number = 1

  The ID of the quorum.

• uint32 adversary_threshold_percentage = 2

  The max percentage of stake within the quorum that can be held by or delegated to adversarial operators. Currently, this and the next parameter are standardized across the quorum using values read from the EigenDA contracts.

• uint32 confirmation_threshold_percentage = 3

  The min percentage of stake that must attest in order to consider the dispersal is successful.

• uint32 chunk_length = 4

  The length of each chunk.

BlobStatus represents the status of a blob. The status of a blob is updated as the blob is processed by the disperser. The status of a blob can be queried by the client using the GetBlobStatus API. Intermediate states are states that the blob can be in while being processed, and it can be updated to a different state: - PROCESSING - DISPERSING - CONFIRMED Terminal states are states that will not be updated to a different state: - FAILED - FINALIZED - INSUFFICIENT_SIGNATURES

Used in: BlobStatusReply, DisperseBlobReply

• UNKNOWN = 0

• PROCESSING = 1

  PROCESSING means that the blob is currently being processed by the disperser

• CONFIRMED = 2

  CONFIRMED means that the blob has been dispersed to DA Nodes and the dispersed batch containing the blob has been confirmed onchain

• FAILED = 3

  FAILED means that the blob has failed permanently (for reasons other than insufficient signatures, which is a separate state). This status is somewhat of a catch-all category, containing (but not necessarily exclusively as errors can be added in the future): - blob has expired - internal logic error while requesting encoding - blob retry has exceeded its limit while waiting for blob finalization after confirmation. Most likely triggered by a chain reorg: see https://github.com/Layr-Labs/eigenda/blob/master/disperser/batcher/finalizer.go#L179-L189.

• FINALIZED = 4

  FINALIZED means that the block containing the blob's confirmation transaction has been finalized on Ethereum

• INSUFFICIENT_SIGNATURES = 5

  INSUFFICIENT_SIGNATURES means that the confirmation threshold for the blob was not met for at least one quorum.

• DISPERSING = 6

  The DISPERSING state is comprised of two separate phases: - Dispersing to DA nodes and collecting signature - Submitting the transaction on chain and waiting for tx receipt

Used in: BlobInfo

• uint32 batch_id = 1

  batch_id is an incremental ID assigned to a batch by EigenDAServiceManager

• uint32 blob_index = 2

  The index of the blob in the batch (which is logically an ordered list of blobs).

• optional BatchMetadata batch_metadata = 3

• bytes inclusion_proof = 4

  inclusion_proof is a merkle proof for a blob header's inclusion in a batch

• bytes quorum_indexes = 5

  indexes of quorums in BatchHeader.quorum_numbers that match the quorums in BlobHeader.blob_quorum_params Ex. BlobHeader.blob_quorum_params = [ { quorum_number = 0, ... }, { quorum_number = 3, ... }, { quorum_number = 5, ... }, ] BatchHeader.quorum_numbers = [0, 5, 3] => 0x000503 Then, quorum_indexes = [0, 2, 1] => 0x000201

Used as response type in: Disperser.DisperseBlob

Used as field type in: AuthenticatedReply

• BlobStatus result = 1

  The status of the blob associated with the request_id. Will always be PROCESSING.

• bytes request_id = 2

  The request ID generated by the disperser. Once a request is accepted, a unique request ID is generated. request_id = string(blob_key) = (hash(blob), hash(metadata)) where metadata contains a requestedAt timestamp and the requested quorum numbers and their adversarial thresholds. BlobKey definition: https://github.com/Layr-Labs/eigenda/blob/6b02bf966afa2b9bf2385db8dd01f66f17334e17/disperser/disperser.go#L87 BlobKey computation: https://github.com/Layr-Labs/eigenda/blob/6b02bf966afa2b9bf2385db8dd01f66f17334e17/disperser/common/blobstore/shared_storage.go#L83-L84 Different DisperseBlobRequests have different IDs, including two identical DisperseBlobRequests sent at different times. Clients should thus store this ID and use it to query the processing status of the request via the GetBlobStatus API.

Used as request type in: Disperser.DisperseBlob

Used as field type in: AuthenticatedRequest

• bytes data = 1

  The data to be dispersed. The size of data must be <= 16MiB. Every 32 bytes of data is interpreted as an integer in big endian format where the lower address has more significant bits. The integer must stay in the valid range to be interpreted as a field element on the bn254 curve. The valid range is 0 <= x < 21888242871839275222246405745257275088548364400416034343698204186575808495617 If any one of the 32 bytes elements is outside the range, the whole request is deemed as invalid, and rejected.

• repeated uint32 custom_quorum_numbers = 2

  The quorums to which the blob will be sent, in addition to the required quorums which are configured on the EigenDA smart contract. If required quorums are included here, an error will be returned. The disperser will ensure that the encoded blobs for each quorum are all processed within the same batch.

• string account_id = 3

  The account ID of the client. This should be a hex-encoded string of the ECDSA public key corresponding to the key used by the client to sign the BlobAuthHeader.