Protocol Documentation
Table of Contents
disperser/v2/disperser_v2.proto
Attestation
| Field | Type | Label | Description |
|---|---|---|---|
| non_signer_pubkeys | bytes | repeated | Serialized bytes of non signer public keys (G1 points) |
| apk_g2 | bytes | Serialized bytes of G2 point that represents aggregate public key of all signers | |
| quorum_apks | bytes | repeated | Serialized bytes of aggregate public keys (G1 points) from all nodes for each quorum The order of the quorum_apks should match the order of the quorum_numbers |
| sigma | bytes | Serialized bytes of aggregate signature | |
| quorum_numbers | uint32 | repeated | Relevant quorum numbers for the attestation |
| quorum_signed_percentages | bytes | The attestation rate for each quorum. Each quorum's signing percentage is represented by an 8 bit unsigned integer. The integer is the fraction of the quorum that has signed, with 100 representing 100% of the quorum signing, and 0 representing 0% of the quorum signing. The first byte in the byte array corresponds to the first quorum in the quorum_numbers array, the second byte corresponds to the second quorum, and so on. |
BlobCommitmentReply
The result of a BlobCommitmentRequest().
| Field | Type | Label | Description |
|---|---|---|---|
| blob_commitment | common.BlobCommitment | The commitment of the blob. |
BlobCommitmentRequest
The input for a BlobCommitmentRequest(). This can be used to construct a BlobHeader.commitment.
| Field | Type | Label | Description |
|---|---|---|---|
| blob | bytes | The blob data to compute the commitment for. |
BlobInclusionInfo
BlobInclusionInfo is the information needed to verify the inclusion of a blob in a batch.
| Field | Type | Label | Description |
|---|---|---|---|
| blob_certificate | common.v2.BlobCertificate | ||
| blob_index | uint32 | blob_index is the index of the blob in the batch | |
| inclusion_proof | bytes | inclusion_proof is the inclusion proof of the blob in the batch |
BlobStatusReply
BlobStatusReply is the reply to a BlobStatusRequest.
| Field | Type | Label | Description |
|---|---|---|---|
| status | BlobStatus | The status of the blob. | |
| signed_batch | SignedBatch | The signed batch. Only set if the blob status is GATHERING_SIGNATURES or COMPLETE. signed_batch and blob_inclusion_info are only set if the blob status is GATHERING_SIGNATURES or COMPLETE. When blob is in GATHERING_SIGNATURES status, the attestation object in signed_batch contains attestation information at the point in time. As it gathers more signatures, attestation object will be updated according to the latest attestation status. The client can use this intermediate attestation to verify a blob if it has gathered enough signatures. Otherwise, it should should poll the GetBlobStatus API until the desired level of attestation has been gathered or status is COMPLETE. When blob is in COMPLETE status, the attestation object in signed_batch contains the final attestation information. If the final attestation does not meet the client's requirement, the client should try a new dispersal. | |
| blob_inclusion_info | BlobInclusionInfo | BlobInclusionInfo is the information needed to verify the inclusion of a blob in a batch. Only set if the blob status is GATHERING_SIGNATURES or COMPLETE. |
BlobStatusRequest
BlobStatusRequest is used to query the status of a blob.
| Field | Type | Label | Description |
|---|---|---|---|
| blob_key | bytes | The unique identifier for the blob. |
DisperseBlobReply
A reply to a DisperseBlob request.
| Field | Type | Label | Description |
|---|---|---|---|
| result | BlobStatus | The status of the blob associated with the blob key. | |
| blob_key | bytes | The unique 32 byte identifier for the blob. |
The blob_key is the keccak hash of the rlp serialization of the BlobHeader, as computed here: https://github.com/Layr-Labs/eigenda/blob/0f14d1c90b86d29c30ff7e92cbadf2762c47f402/core/v2/serialization.go#L30 The blob_key must thus be unique for every request, even if the same blob is being dispersed. Meaning the blob_header must be different for each request.
Note that attempting to disperse a blob with the same blob key as a previously dispersed blob may cause the disperser to reject the blob (DisperseBlob() RPC will return an error). |
DisperseBlobRequest
A request to disperse a blob.
| Field | Type | Label | Description |
|---|---|---|---|
| blob | bytes | The blob to be dispersed. |
The size of this byte array may be any size as long as it does not exceed the maximum length of 16MiB. While the data being dispersed is only required to be greater than 0 bytes, the blob size charged against the payment method will be rounded up to the nearest multiple of minNumSymbols defined by the payment vault contract (https://github.com/Layr-Labs/eigenda/blob/1430d56258b4e814b388e497320fd76354bfb478/contracts/src/payments/PaymentVaultStorage.sol#L9).
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. | | blob_header | common.v2.BlobHeader | | The header contains metadata about the blob.
This header can be thought of as an "eigenDA tx", in that it plays a purpose similar to an eth_tx to disperse a 4844 blob. Note that a call to DisperseBlob requires the blob and the blobHeader, which is similar to how dispersing a blob to ethereum requires sending a tx whose data contains the hash of the kzg commit of the blob, which is dispersed separately. | | signature | bytes | | signature over keccak hash of the blob_header that can be verified by blob_header.payment_header.account_id |
GetPaymentStateReply
GetPaymentStateReply contains the payment state of an account.
| Field | Type | Label | Description |
|---|---|---|---|
| payment_global_params | PaymentGlobalParams | global payment vault parameters | |
| period_records | PeriodRecord | repeated | off-chain account reservation usage records |
| reservation | Reservation | on-chain account reservation setting | |
| cumulative_payment | bytes | off-chain on-demand payment usage | |
| onchain_cumulative_payment | bytes | on-chain on-demand payment deposited |
GetPaymentStateRequest
GetPaymentStateRequest contains parameters to query the payment state of an account.
| Field | Type | Label | Description |
|---|---|---|---|
| account_id | string | The ID of the account being queried. This account ID is an eth wallet address of the user. | |
| signature | bytes | Signature over the account ID |
PaymentGlobalParams
Global constant parameters defined by the payment vault.
| Field | Type | Label | Description |
|---|---|---|---|
| global_symbols_per_second | uint64 | Global ratelimit for on-demand dispersals | |
| min_num_symbols | uint64 | Minimum number of symbols accounted for all dispersals | |
| price_per_symbol | uint64 | Price charged per symbol for on-demand dispersals | |
| reservation_window | uint64 | Reservation window for all reservations | |
| on_demand_quorum_numbers | uint32 | repeated | quorums allowed to make on-demand dispersals |
PeriodRecord
PeriodRecord is the usage record of an account in a bin. The API should return the active bin record and the subsequent two records that contains potential overflows.
| Field | Type | Label | Description |
|---|---|---|---|
| index | uint32 | Period index of the reservation | |
| usage | uint64 | symbol usage recorded |
Reservation
Reservation parameters of an account, used to determine the rate limit for the account.
| Field | Type | Label | Description |
|---|---|---|---|
| symbols_per_second | uint64 | rate limit for the account | |
| start_timestamp | uint32 | start timestamp of the reservation | |
| end_timestamp | uint32 | end timestamp of the reservation | |
| quorum_numbers | uint32 | repeated | quorums allowed to make reserved dispersals |
| quorum_splits | uint32 | repeated | quorum splits describes how the payment is split among the quorums |
SignedBatch
SignedBatch is a batch of blobs with a signature.
| Field | Type | Label | Description |
|---|---|---|---|
| header | common.v2.BatchHeader | header contains metadata about the batch | |
| attestation | Attestation | attestation on the batch |
BlobStatus
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:
- QUEUED
- ENCODED
- GATHERING_SIGNATURES Terminal states are states that will not be updated to a different state:
- UNKNOWN
- COMPLETE
- FAILED
| Name | Number | Description |
|---|---|---|
| UNKNOWN | 0 | UNKNOWN means that the status of the blob is unknown. This is a catch all and should not be encountered absent a bug. |
This status is functionally equivalent to FAILED, but is used to indicate that the failure is due to an unanticipated bug. | | QUEUED | 1 | QUEUED means that the blob has been queued by the disperser for processing. The DisperseBlob API is asynchronous, meaning that after request validation, but before any processing, the blob is stored in a queue of some sort, and a response immediately returned to the client. | | ENCODED | 2 | ENCODED means that the blob has been Reed-Solomon encoded into chunks and is ready to be dispersed to DA Nodes. | | GATHERING_SIGNATURES | 3 | GATHERING_SIGNATURES means that the blob chunks are currently actively being transmitted to validators, and in doing so requesting that the validators sign to acknowledge receipt of the blob. Requests that timeout or receive errors are resubmitted to DA nodes for some period of time set by the disperser, after which the BlobStatus becomes COMPLETE. | | COMPLETE | 4 | COMPLETE means the blob has been dispersed to DA nodes, and the GATHERING_SIGNATURES period of time has completed. This status does not guarantee any signer percentage, so a client should check that the signature has met its required threshold, and resubmit a new blob dispersal request if not. | | FAILED | 5 | FAILED means that the blob has failed permanently. Note that this is a terminal state, and in order to retry the blob, the client must submit the blob again (blob key is required to be unique). |
Disperser
Disperser defines the public APIs for dispersing blobs.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| DisperseBlob | DisperseBlobRequest | DisperseBlobReply | DisperseBlob accepts blob to disperse from clients. This executes the dispersal asynchronously, i.e. it returns once the request is accepted. The client could use GetBlobStatus() API to poll the the processing status of the blob. |
| GetBlobStatus | BlobStatusRequest | BlobStatusReply | GetBlobStatus is meant to be polled for the blob status. |
| GetBlobCommitment | BlobCommitmentRequest | BlobCommitmentReply | GetBlobCommitment is a utility method that calculates commitment for a blob payload. |
| GetPaymentState | GetPaymentStateRequest | GetPaymentStateReply | GetPaymentState is a utility method to get the payment state of a given account. |