package common.v2

Get desktop application:
View/edit binary Protocol Buffers messages

Batch is a batch of blob certificates

Used in: validator.StoreChunksRequest

• optional BatchHeader header = 1

  header contains metadata about the batch

• repeated BlobCertificate blob_certificates = 2

  blob_certificates is the list of blob certificates in the batch

BatchHeader is the header of a batch of blobs

Used in: Batch, disperser.v2.SignedBatch

• bytes batch_root = 1

  batch_root is the root of the merkle tree of the hashes of blob certificates in the batch

• uint64 reference_block_number = 2

  reference_block_number is the block number that the state of the batch is based on for attestation

BlobCertificate contains a full description of a blob and how it is dispersed. Part of the certificate is provided by the blob submitter (i.e. the blob header), and part is provided by the disperser (i.e. the relays). Validator nodes eventually sign the blob certificate once they are in custody of the required chunks (note that the signature is indirect; validators sign the hash of a Batch, which contains the blob certificate).

Used in: Batch, disperser.v2.BlobInclusionInfo

• optional BlobHeader blob_header = 1

  blob_header contains data about the blob.

• bytes signature = 2

  signature is an ECDSA signature signed by the blob request signer's account ID over the BlobHeader's blobKey, which is a keccak hash of the serialized BlobHeader, and used to verify against blob dispersal request's account ID

• repeated uint32 relay_keys = 3

  relay_keys is the list of relay keys that are in custody of the blob. The relays custodying the data are chosen by the Disperser to which the DisperseBlob request was submitted. It needs to contain at least 1 relay number. To retrieve a blob from the relay, one can find that relay's URL in the EigenDARelayRegistry contract: https://github.com/Layr-Labs/eigenda/blob/master/contracts/src/core/EigenDARelayRegistry.sol

BlobHeader contains the information describing a blob and the way it is to be dispersed.

Used in: BlobCertificate, controller.AuthorizePaymentRequest, disperser.v2.DisperseBlobRequest, retriever.v2.BlobRequest

• uint32 version = 1

  The BlobParams version to use when encoding the blob into chunks to be dispersed to operators. BlobParams versions are pushed onchain to the EigenDAThresholdRegistry by EigenDA governance in an append only fashion and store the maximum number of operators, number of chunks, and coding rate for a blob. A user can choose any of the onchain defined VersionedBlobParams, and must make sure to choose SecurityThresholds in its CertVerifier contract that along with the chosen VersionedBlobParams satisfy the checkSecurityParams function: https://github.com/Layr-Labs/eigenda/blob/3e670ff3dbd3a0a3f63b51e40544f528ac923b78/contracts/src/periphery/cert/libraries/EigenDACertVerificationLib.sol#L188 This function is called internally by the CertVerifier's checkDACert function. If a version that is not available on the ThresholdRegistry is chosen, the disperser will return an error. EigenDA maintained: VersionedBlobParams definition: https://github.com/Layr-Labs/eigenda/blob/3e670ff3dbd3a0a3f63b51e40544f528ac923b78/contracts/src/core/libraries/v1/EigenDATypesV1.sol#L7 IEigenDAThresholdRegistry (stores the BlobParams): https://github.com/Layr-Labs/eigenda/blob/3e670ff3dbd3a0a3f63b51e40544f528ac923b78/contracts/src/core/interfaces/IEigenDAThresholdRegistry.sol EigenDAServiceManager address (implements IEigenDAThresholdRegistry): https://docs.eigenda.xyz/networks/mainnet#contract-addresses Rollup maintained: SecurityThresholds interface: https://github.com/Layr-Labs/eigenda/blob/3e670ff3dbd3a0a3f63b51e40544f528ac923b78/contracts/src/periphery/cert/interfaces/IEigenDACertVerifier.sol#L23 checkDACert interface: https://github.com/Layr-Labs/eigenda/blob/3e670ff3dbd3a0a3f63b51e40544f528ac923b78/contracts/src/periphery/cert/interfaces/IEigenDACertVerifierBase.sol#L8

• repeated uint32 quorum_numbers = 2

  quorum_numbers is the list of quorum numbers that the blob shall be dispersed to. Each quorum will store the data independently, meaning that additional quorum numbers increase redundancy, making the blob more likely to be retrievable. Each quorum requires separate payment. On-demand bandwidth dispersals do not currently support custom quorums and hence are limited to dispersing to one or two of the following quorums only: - 0: ETH - 1: EIGEN Reserved-bandwidth dispersal do support custom quorums, as long as they are reserved onchain ahead of time. The quorum_numbers specified here must be a subset of the ones allowed by the on-chain reservation. Users can check their reserved quorum numbers on the IPaymentVault's reservation struct: https://github.com/Layr-Labs/eigenda/blob/1430d56258b4e814b388e497320fd76354bfb478/contracts/src/interfaces/IPaymentVault.sol#L10

• optional BlobCommitment commitment = 3

  commitment is the KZG commitment to the blob.

• optional PaymentHeader payment_header = 4

  payment_header contains payment information for the blob

PaymentHeader contains payment information for a blob. Reservation parameters and on-demand deposits are tracked on-chain in the PaymentVault contract: https://github.com/Layr-Labs/eigenda/blob/master/contracts/src/core/PaymentVault.sol Two payment methods are supported: 1. Reservation: - Users reserve bandwidth in advance for a specified time period. - Reservations are procured out-of-band, and are set in the PaymentVault by the EigenFoundation. 2. On-demand: - Users pay for each dispersal individually from funds deposited into the PaymentVault, by specifying a cumulative payment. - On-demand payments are limited to quorums 0 and 1. - On-demand payments can only be used when dispersing through the EigenDA disperser. Currently, the EigenDA disperser is the *only* disperser, but this restriction will remain in place even with decentralized dispersal. For payment calculations, dispersals have a minimum size of minNumSymbols, defined in the PaymentVault. Smaller blobs are billed as `minNumSymbols`. The cost of an on-demand dispersal is calculated by multiplying the number of blob symbols by the pricePerSymbol defined in the PaymentVault. Note: the quorum set being dispersed to has no impact on payment accounting with the current implementation. TODO(litt3): the current payment usage source-of-truth is the EigenDA disperser: reservation usage and latest cumulative payment is persistently stored there. Once decentralized dispersal has been implemented, the validator nodes will become the source-of-truth for reservation usage, but the EigenDA disperser will remain the source-of-truth for on-demand usage. TODO(litt3): once accounting logic has been properly abstracted, put a link here to provide specific documentation of how payments are processed.

Used in: BlobHeader

• string account_id = 1

  The account ID of the dispersing user, represented as an Ethereum wallet address in hex format (0x prefix optional) This is the unique key which identifies the reservation to use, or the on-demand payment account to debit. The account ID must correspond to the key used to sign the dispersal request for the payment to be valid.

• int64 timestamp = 2

  The timestamp represents the nanosecond UNIX timestamp at the time the dispersal request is created. The timestamp plays the role of a nonce, optionally allowing the same blob data to be dispersed multiple times while still having a unique blob header hash (which is used as an idempotency key). When dealing with reservations, the timestamp determines which reservation bucket the dispersal falls into. TODO(litt3): there is an ongoing effort to use a leaky bucket algorithm instead of a fixed window algorithm to track reservation usage. The timestamp is currently used for the fixed window algorithm, but will not be part of the leaky bucket algorithm. Even after this change, the timestamp should still be populated. The timestamp is currently unused in the context of on-demand payments, but this is subject to change without notice! Failure to populate this with a proper timestamp could result in failed dispersals and loss of associated payments.

• bytes cumulative_payment = 3

  The cumulative_payment field is a variable-sized big endian unsigned integer, representing the total wei paid by the account for this and all previous dispersals. TODO(litt3): we ought to limit the max size of this field to 32 bytes (256-bit unsigned int), but this isn't currently being checked. This will be fixed during the ongoing accounting reimplementation. For example, assume a new user begins dispersing blobs with on-demand payments, and each blob costs 100 wei. For the first dispersed blob, the cumulative_payment would be set to 100. For the second, 200. Then 300, and so on. If this field is *not* set, or is zero, reservation accounting will be used. If this field *is* set, and non-zero, on-demand accounting will be used EVEN IF a given account has a reservation. There is no fallback between these payment mechanisms: the dispersal will either succeed or fail on the basis of the implicitly defined payment mechanism, regardless of whether the alternate mechanism would have succeeded. Since the cumulative payment covers all historical on-demand dispersals, a client starting up must obtain the value of the latest cumulative payment for its account via the GetPaymentState disperser RPC. IMPORTANT: With the current implementation, the cumulative payment of dispersals must be strictly increasing from the perspective of the entity doing the accounting. If a given cumulative payment X is <= the cumulative payment of a previous dispersal, then X is considered to be invalid. The implication is that a user must not behave in any way that could result in payments being processed out of order, or risk dispersals failing without refund. In practice, that means waiting for confirmation from the disperser that a blob has been received before submitting the next blob. TODO(litt3): to weaken this requirement, the accounting logic would need to be modified, such that up to `n` recent on-demand payments are tracked, allowing for safe dispersal of up to `n` concurrent on-demand blobs.