package disperser.v2
Get desktop application:
View/edit binary Protocol Buffers messages
service Disperser
disperser_v2.proto:10Disperser defines the public APIs for dispersing blobs.
rpc DisperseBlob (, )
disperser_v2.proto:15DisperseBlob 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.
message
disperser_v2.proto:42A request to disperse a blob.
bytes blob = 1
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.
optional blob_header = 2
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.
bytes signature = 3
signature over keccak hash of the blob_header that can be verified by blob_header.payment_header.account_id
message
disperser_v2.proto:67A reply to a DisperseBlob request.
BlobStatus result = 1
The status of the blob associated with the blob key.
bytes blob_key = 2
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).
rpc GetBlobStatus (, )
disperser_v2.proto:18GetBlobStatus is meant to be polled for the blob status.
message
disperser_v2.proto:83BlobStatusRequest is used to query the status of a blob.
bytes blob_key = 1
The unique identifier for the blob.
message
disperser_v2.proto:89BlobStatusReply is the reply to a BlobStatusRequest.
BlobStatus status = 1
The status of the blob.
optional signed_batch = 2
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.
optional blob_inclusion_info = 3
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.
GetBlobCommitment is a utility method that calculates commitment for a blob payload. It is provided to help clients who are trying to construct a DisperseBlobRequest.blob_header and don't have the ability to calculate the commitment themselves (expensive operation which requires SRS points). For an example usage, see how our disperser_client makes a call to this endpoint when it doesn't have a local prover: https://github.com/Layr-Labs/eigenda/blob/6059c6a068298d11c41e50f5bcd208d0da44906a/api/clients/v2/disperser_client.go#L166
message
disperser_v2.proto:108The input for a BlobCommitmentRequest(). This can be used to construct a BlobHeader.commitment.
bytes blob = 1
The blob data to compute the commitment for.
message
disperser_v2.proto:114The result of a BlobCommitmentRequest().
optional blob_commitment = 1
The commitment of the blob.
rpc GetPaymentState (, )
disperser_v2.proto:36GetPaymentState is a utility method to get the payment state of a given account, at a given disperser. EigenDA's payment system for v2 is currently centralized, meaning that each disperser does its own accounting. A client wanting to disperse a blob would thus need to synchronize its local accounting state with that of the disperser. That typically only needs to be done once, and the state can be updated locally as the client disperses blobs. The accounting rules are simple and can be updated locally, but periodic checks with the disperser can't hurt. For an example usage, see how our disperser_client makes a call to this endpoint to populate its local accountant struct: https://github.com/Layr-Labs/eigenda/blob/6059c6a068298d11c41e50f5bcd208d0da44906a/api/clients/v2/disperser_client.go#L298
message
disperser_v2.proto:120GetPaymentStateRequest contains parameters to query the payment state of an account.
string account_id = 1
The ID of the account being queried. This account ID is an eth wallet address of the user.
bytes signature = 2
Signature over the account ID
uint64 timestamp = 3
Timestamp of the request in nanoseconds since the Unix epoch. If too far out of sync with the server's clock, request may be rejected.
message
disperser_v2.proto:131GetPaymentStateReply contains the payment state of an account.
optional payment_global_params = 1
global payment vault parameters
repeated period_records = 2
off-chain account reservation usage records
optional reservation = 3
on-chain account reservation setting
bytes cumulative_payment = 4
off-chain on-demand payment usage
bytes onchain_cumulative_payment = 5
on-chain on-demand payment deposited
message
disperser_v2.proto:206Used in:
repeated bytes non_signer_pubkeys = 1
Serialized bytes of non signer public keys (G1 points)
bytes apk_g2 = 2
Serialized bytes of G2 point that represents aggregate public key of all signers
repeated bytes quorum_apks = 3
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
bytes sigma = 4
Serialized bytes of aggregate signature
repeated uint32 quorum_numbers = 5
Relevant quorum numbers for the attestation
bytes quorum_signed_percentages = 6
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.
message
disperser_v2.proto:198BlobInclusionInfo is the information needed to verify the inclusion of a blob in a batch.
Used in:
optional blob_certificate = 1
uint32 blob_index = 2
blob_index is the index of the blob in the batch
bytes inclusion_proof = 3
inclusion_proof is the inclusion proof of the blob in the batch
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
Used in: ,
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).
message
disperser_v2.proto:227Global constant parameters defined by the payment vault.
Used in:
uint64 global_symbols_per_second = 1
Global ratelimit for on-demand dispersals
uint64 min_num_symbols = 2
Minimum number of symbols accounted for all dispersals
uint64 price_per_symbol = 3
Price charged per symbol for on-demand dispersals
uint64 reservation_window = 4
Reservation window for all reservations
repeated uint32 on_demand_quorum_numbers = 5
quorums allowed to make on-demand dispersals
message
disperser_v2.proto:256PeriodRecord 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.
Used in:
uint32 index = 1
Period index of the reservation
uint64 usage = 2
symbol usage recorded
message
disperser_v2.proto:241Reservation parameters of an account, used to determine the rate limit for the account.
Used in:
uint64 symbols_per_second = 1
rate limit for the account
uint32 start_timestamp = 2
start timestamp of the reservation
uint32 end_timestamp = 3
end timestamp of the reservation
repeated uint32 quorum_numbers = 4
quorums allowed to make reserved dispersals
repeated uint32 quorum_splits = 5
quorum splits describes how the payment is split among the quorums
message
disperser_v2.proto:190SignedBatch is a batch of blobs with a signature.
Used in:
optional header = 1
header contains metadata about the batch
optional attestation = 2
attestation on the batch