BlobHeader contains the information needed to disperse a blob to the EigenDA network.
It 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 who's data contains the hash of the kzg commit of the blob, which is
dispersed separately.
+ BlobHeader contains the information needed to disperse a blob to the EigenDA network.
@@ -1152,7 +1152,7 @@
| commitment |
common.BlobCommitment |
|
- commitment is the KZG commitment of the blob |
+ commitment is the KZG commitment to the blob |
@@ -2202,8 +2202,11 @@ DisperseBlobReply
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 disperser.
-Meaning the blob_header must be different for each request.
+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).
@@ -2242,7 +2245,12 @@ DisperseBlobRequest
blob_header |
common.v2.BlobHeader |
|
- The header contains metadata about the blob. |
+ 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. |
@@ -2318,7 +2326,7 @@ GetPaymentStateRequest
account_id |
string |
|
- The ID of the account being queried. |
+ The ID of the account being queried. This account ID is an eth wallet address of the user. |
@@ -2505,7 +2513,7 @@ SignedBatch
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
Terminal states are states that will not be updated to a different state:
- CERTIFIED
- FAILED
- INSUFFICIENT_SIGNATURES
- UNKNOWN
+ 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
Terminal states are states that will not be updated to a different state:
- UNKNOWN
- CERTIFIED
- FAILED
- INSUFFICIENT_SIGNATURES
| Name | Number | Description |
@@ -2516,7 +2524,10 @@ BlobStatus
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 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.
@@ -2542,13 +2553,17 @@ BlobStatus
| FAILED |
4 |
- FAILED means that the blob has failed permanently. |
+ 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 with different salt (blob key is required to be unique). |
| INSUFFICIENT_SIGNATURES |
5 |
- INSUFFICIENT_SIGNATURES means that the blob has failed to gather sufficient attestation. |
+ INSUFFICIENT_SIGNATURES means that the blob has failed to gather sufficient attestation.
+
+This status is functionally equivalent to FAILED, but is used to indicate that the failure is due to an
+an inability to gather sufficient signatures. |
@@ -3513,7 +3528,7 @@ GetNodeInfoReply
GetNodeInfoRequest
- The parameter for the NodeInfo() RPC.
+ The parameter for the GetNodeInfo() RPC.
@@ -3614,7 +3629,7 @@ StoreChunksRequest
Dispersal
- Dispersal is utilized to disperse chunk data. The disperser calls these RPCs to store chunks on individual DA nodes.
+ Dispersal is utilized to disperse chunk data.
| Method Name | Request Type | Response Type | Description |
@@ -3632,7 +3647,7 @@ Dispersal
GetNodeInfo |
GetNodeInfoRequest |
GetNodeInfoReply |
- NodeInfo fetches metadata about the node. |
+ GetNodeInfo fetches metadata about the node. |
@@ -3640,7 +3655,7 @@ Dispersal
Retrieval
- Retrieval is utilized to retrieve chunk data. This chunk data can be used to reconstruct the original blob.
+ Retrieval is utilized to retrieve chunk data.
| Method Name | Request Type | Response Type | Description |
diff --git a/api/docs/eigenda-protos.md b/api/docs/eigenda-protos.md
index 0df7f435d..bde47c2b8 100644
--- a/api/docs/eigenda-protos.md
+++ b/api/docs/eigenda-protos.md
@@ -353,7 +353,7 @@ It gets constructed by the Disperser to which the DisperseBlob request was submi
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
-| blob_header | [BlobHeader](#common-v2-BlobHeader) | | blob_header contains metadata about the blob. The hash of this header is used to compute the blob key. |
+| blob_header | [BlobHeader](#common-v2-BlobHeader) | | blob_header contains metadata about the blob. |
| relays | [uint32](#uint32) | repeated | relays is the list of relays 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 |
@@ -365,10 +365,6 @@ It gets constructed by the Disperser to which the DisperseBlob request was submi
### BlobHeader
BlobHeader contains the information needed to disperse a blob to the EigenDA network.
-It 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 who's data contains the hash of the kzg commit of the blob, which is
-dispersed separately.
| Field | Type | Label | Description |
@@ -377,7 +373,7 @@ dispersed separately.
| quorum_numbers | [uint32](#uint32) | repeated | quorum_numbers is the list of quorum numbers that the blob is part of. All quorums must be specified (including required quorums).
The following quorums are currently required: - 0: ETH - 1: EIGEN |
-| commitment | [common.BlobCommitment](#common-BlobCommitment) | | commitment is the KZG commitment of the blob |
+| commitment | [common.BlobCommitment](#common-BlobCommitment) | | commitment is the KZG commitment to the blob |
| payment_header | [common.PaymentHeader](#common-PaymentHeader) | | payment_header contains payment information for the blob |
| signature | [bytes](#bytes) | | signature over keccak hash of the blob_header that can be verified by blob_header.account_id |
@@ -860,7 +856,9 @@ A reply to a DisperseBlob request.
| result | [BlobStatus](#disperser-v2-BlobStatus) | | The status of the blob associated with the blob key. |
| blob_key | [bytes](#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 disperser. Meaning the blob_header must be different for each request. |
+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). |
@@ -880,7 +878,9 @@ A request to disperse a blob.
The size of this byte array may be any size as long as it does not exceed the maximum length of 16MiB. (In the future, the 16MiB limit may be increased, but this is not guaranteed to happen.)
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](#common-v2-BlobHeader) | | The header contains metadata about the blob. |
+| blob_header | [common.v2.BlobHeader](#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. |
@@ -914,7 +914,7 @@ GetPaymentStateRequest contains parameters to query the payment state of an acco
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
-| account_id | [string](#string) | | The ID of the account being queried. |
+| account_id | [string](#string) | | The ID of the account being queried. This account ID is an eth wallet address of the user. |
| signature | [bytes](#bytes) | | Signature over the account ID TODO: sign over a reservation period or a nonce to mitigate signature replay attacks |
@@ -1005,19 +1005,23 @@ Intermediate states are states that the blob can be in while being processed, an
- QUEUED
- ENCODED
Terminal states are states that will not be updated to a different state:
+- UNKNOWN
- CERTIFIED
- FAILED
- INSUFFICIENT_SIGNATURES
-- UNKNOWN
| 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. |
+| 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. |
| CERTIFIED | 3 | CERTIFIED means the blob has been dispersed and attested by the DA nodes. |
-| FAILED | 4 | FAILED means that the blob has failed permanently. |
-| INSUFFICIENT_SIGNATURES | 5 | INSUFFICIENT_SIGNATURES means that the blob has failed to gather sufficient attestation. |
+| FAILED | 4 | 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 with different salt (blob key is required to be unique). |
+| INSUFFICIENT_SIGNATURES | 5 | INSUFFICIENT_SIGNATURES means that the blob has failed to gather sufficient attestation.
+
+This status is functionally equivalent to FAILED, but is used to indicate that the failure is due to an an inability to gather sufficient signatures. |
@@ -1473,7 +1477,7 @@ Node info reply
### GetNodeInfoRequest
-The parameter for the NodeInfo() RPC.
+The parameter for the GetNodeInfo() RPC.
@@ -1527,18 +1531,18 @@ Note that this signature is not included in the hash for obvious reasons. |
### Dispersal
-Dispersal is utilized to disperse chunk data. The disperser calls these RPCs to store chunks on individual DA nodes.
+Dispersal is utilized to disperse chunk data.
| Method Name | Request Type | Response Type | Description |
| ----------- | ------------ | ------------- | ------------|
| StoreChunks | [StoreChunksRequest](#node-v2-StoreChunksRequest) | [StoreChunksReply](#node-v2-StoreChunksReply) | StoreChunks stores a batch of chunks on the Node. |
-| GetNodeInfo | [GetNodeInfoRequest](#node-v2-GetNodeInfoRequest) | [GetNodeInfoReply](#node-v2-GetNodeInfoReply) | NodeInfo fetches metadata about the node. |
+| GetNodeInfo | [GetNodeInfoRequest](#node-v2-GetNodeInfoRequest) | [GetNodeInfoReply](#node-v2-GetNodeInfoReply) | GetNodeInfo fetches metadata about the node. |
### Retrieval
-Retrieval is utilized to retrieve chunk data. This chunk data can be used to reconstruct the original blob.
+Retrieval is utilized to retrieve chunk data.
| Method Name | Request Type | Response Type | Description |
| ----------- | ------------ | ------------- | ------------|
diff --git a/api/docs/node_v2.html b/api/docs/node_v2.html
index b06c52486..de11080f6 100644
--- a/api/docs/node_v2.html
+++ b/api/docs/node_v2.html
@@ -340,7 +340,7 @@ GetNodeInfoReply
GetNodeInfoRequest
- The parameter for the NodeInfo() RPC.
+ The parameter for the GetNodeInfo() RPC.
@@ -441,7 +441,7 @@ StoreChunksRequest
Dispersal
- Dispersal is utilized to disperse chunk data. The disperser calls these RPCs to store chunks on individual DA nodes.
+ Dispersal is utilized to disperse chunk data.
| Method Name | Request Type | Response Type | Description |
@@ -459,7 +459,7 @@ Dispersal
GetNodeInfo |
GetNodeInfoRequest |
GetNodeInfoReply |
- NodeInfo fetches metadata about the node. |
+ GetNodeInfo fetches metadata about the node. |
@@ -467,7 +467,7 @@ Dispersal
Retrieval
- Retrieval is utilized to retrieve chunk data. This chunk data can be used to reconstruct the original blob.
+ Retrieval is utilized to retrieve chunk data.
| Method Name | Request Type | Response Type | Description |
diff --git a/api/docs/node_v2.md b/api/docs/node_v2.md
index 377e91082..f5c914bdc 100644
--- a/api/docs/node_v2.md
+++ b/api/docs/node_v2.md
@@ -78,7 +78,7 @@ Node info reply
### GetNodeInfoRequest
-The parameter for the NodeInfo() RPC.
+The parameter for the GetNodeInfo() RPC.
@@ -132,18 +132,18 @@ Note that this signature is not included in the hash for obvious reasons. |
### Dispersal
-Dispersal is utilized to disperse chunk data. The disperser calls these RPCs to store chunks on individual DA nodes.
+Dispersal is utilized to disperse chunk data.
| Method Name | Request Type | Response Type | Description |
| ----------- | ------------ | ------------- | ------------|
| StoreChunks | [StoreChunksRequest](#node-v2-StoreChunksRequest) | [StoreChunksReply](#node-v2-StoreChunksReply) | StoreChunks stores a batch of chunks on the Node. |
-| GetNodeInfo | [GetNodeInfoRequest](#node-v2-GetNodeInfoRequest) | [GetNodeInfoReply](#node-v2-GetNodeInfoReply) | NodeInfo fetches metadata about the node. |
+| GetNodeInfo | [GetNodeInfoRequest](#node-v2-GetNodeInfoRequest) | [GetNodeInfoReply](#node-v2-GetNodeInfoReply) | GetNodeInfo fetches metadata about the node. |
### Retrieval
-Retrieval is utilized to retrieve chunk data. This chunk data can be used to reconstruct the original blob.
+Retrieval is utilized to retrieve chunk data.
| Method Name | Request Type | Response Type | Description |
| ----------- | ------------ | ------------- | ------------|
diff --git a/api/grpc/common/v2/common_v2.pb.go b/api/grpc/common/v2/common_v2.pb.go
index 3440eddc3..af92548d4 100644
--- a/api/grpc/common/v2/common_v2.pb.go
+++ b/api/grpc/common/v2/common_v2.pb.go
@@ -22,10 +22,6 @@ const (
)
// BlobHeader contains the information needed to disperse a blob to the EigenDA network.
-// It 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 who's data contains the hash of the kzg commit of the blob, which is
-// dispersed separately.
type BlobHeader struct {
state protoimpl.MessageState
sizeCache protoimpl.SizeCache
@@ -40,7 +36,7 @@ type BlobHeader struct {
// - 0: ETH
// - 1: EIGEN
QuorumNumbers []uint32 `protobuf:"varint,2,rep,packed,name=quorum_numbers,json=quorumNumbers,proto3" json:"quorum_numbers,omitempty"`
- // commitment is the KZG commitment of the blob
+ // commitment is the KZG commitment to the blob
Commitment *common.BlobCommitment `protobuf:"bytes,3,opt,name=commitment,proto3" json:"commitment,omitempty"`
// payment_header contains payment information for the blob
PaymentHeader *common.PaymentHeader `protobuf:"bytes,4,opt,name=payment_header,json=paymentHeader,proto3" json:"payment_header,omitempty"`
@@ -122,7 +118,7 @@ type BlobCertificate struct {
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
- // blob_header contains metadata about the blob. The hash of this header is used to compute the blob key.
+ // blob_header contains metadata about the blob.
BlobHeader *BlobHeader `protobuf:"bytes,1,opt,name=blob_header,json=blobHeader,proto3" json:"blob_header,omitempty"`
// relays is the list of relays that are in custody of the blob.
// The relays custodying the data are chosen by the Disperser to which the DisperseBlob request was submitted.
diff --git a/api/grpc/disperser/v2/disperser_v2.pb.go b/api/grpc/disperser/v2/disperser_v2.pb.go
index 36fe524ae..31b8263a8 100644
--- a/api/grpc/disperser/v2/disperser_v2.pb.go
+++ b/api/grpc/disperser/v2/disperser_v2.pb.go
@@ -29,15 +29,18 @@ const (
// - QUEUED
// - ENCODED
// Terminal states are states that will not be updated to a different state:
+// - UNKNOWN
// - CERTIFIED
// - FAILED
// - INSUFFICIENT_SIGNATURES
-// - UNKNOWN
type BlobStatus int32
const (
// 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.
BlobStatus_UNKNOWN BlobStatus = 0
// 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,
@@ -47,9 +50,13 @@ const (
BlobStatus_ENCODED BlobStatus = 2
// CERTIFIED means the blob has been dispersed and attested by the DA nodes.
BlobStatus_CERTIFIED BlobStatus = 3
- // FAILED means that the blob has failed permanently.
+ // 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 with different salt (blob key is required to be unique).
BlobStatus_FAILED BlobStatus = 4
// INSUFFICIENT_SIGNATURES means that the blob has failed to gather sufficient attestation.
+ //
+ // This status is functionally equivalent to FAILED, but is used to indicate that the failure is due to an
+ // an inability to gather sufficient signatures.
BlobStatus_INSUFFICIENT_SIGNATURES BlobStatus = 5
)
@@ -117,6 +124,11 @@ type DisperseBlobRequest struct {
// If any one of the 32 bytes elements is outside the range, the whole request is deemed as invalid, and rejected.
Data []byte `protobuf:"bytes,1,opt,name=data,proto3" json:"data,omitempty"`
// 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.
BlobHeader *v2.BlobHeader `protobuf:"bytes,2,opt,name=blob_header,json=blobHeader,proto3" json:"blob_header,omitempty"`
}
@@ -178,8 +190,11 @@ type DisperseBlobReply struct {
//
// 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 disperser.
+ // 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).
BlobKey []byte `protobuf:"bytes,2,opt,name=blob_key,json=blobKey,proto3" json:"blob_key,omitempty"`
}
@@ -451,7 +466,7 @@ type GetPaymentStateRequest struct {
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
- // The ID of the account being queried.
+ // The ID of the account being queried. This account ID is an eth wallet address of the user.
AccountId string `protobuf:"bytes,1,opt,name=account_id,json=accountId,proto3" json:"account_id,omitempty"`
// Signature over the account ID
// TODO: sign over a reservation period or a nonce to mitigate signature replay attacks
diff --git a/api/grpc/node/v2/node_v2.pb.go b/api/grpc/node/v2/node_v2.pb.go
index 26261590b..c4e9ee82c 100644
--- a/api/grpc/node/v2/node_v2.pb.go
+++ b/api/grpc/node/v2/node_v2.pb.go
@@ -274,7 +274,7 @@ func (x *GetChunksReply) GetChunks() [][]byte {
return nil
}
-// The parameter for the NodeInfo() RPC.
+// The parameter for the GetNodeInfo() RPC.
type GetNodeInfoRequest struct {
state protoimpl.MessageState
sizeCache protoimpl.SizeCache
diff --git a/api/grpc/node/v2/node_v2_grpc.pb.go b/api/grpc/node/v2/node_v2_grpc.pb.go
index 67d0ff59a..addb23892 100644
--- a/api/grpc/node/v2/node_v2_grpc.pb.go
+++ b/api/grpc/node/v2/node_v2_grpc.pb.go
@@ -29,7 +29,7 @@ const (
type DispersalClient interface {
// StoreChunks stores a batch of chunks on the Node.
StoreChunks(ctx context.Context, in *StoreChunksRequest, opts ...grpc.CallOption) (*StoreChunksReply, error)
- // NodeInfo fetches metadata about the node.
+ // GetNodeInfo fetches metadata about the node.
GetNodeInfo(ctx context.Context, in *GetNodeInfoRequest, opts ...grpc.CallOption) (*GetNodeInfoReply, error)
}
@@ -65,7 +65,7 @@ func (c *dispersalClient) GetNodeInfo(ctx context.Context, in *GetNodeInfoReques
type DispersalServer interface {
// StoreChunks stores a batch of chunks on the Node.
StoreChunks(context.Context, *StoreChunksRequest) (*StoreChunksReply, error)
- // NodeInfo fetches metadata about the node.
+ // GetNodeInfo fetches metadata about the node.
GetNodeInfo(context.Context, *GetNodeInfoRequest) (*GetNodeInfoReply, error)
mustEmbedUnimplementedDispersalServer()
}
diff --git a/api/proto/common/v2/common_v2.proto b/api/proto/common/v2/common_v2.proto
index f0f39c0d9..dac7f37f7 100644
--- a/api/proto/common/v2/common_v2.proto
+++ b/api/proto/common/v2/common_v2.proto
@@ -4,10 +4,6 @@ import "common/common.proto";
option go_package = "github.com/Layr-Labs/eigenda/api/grpc/common/v2";
// BlobHeader contains the information needed to disperse a blob to the EigenDA network.
-// It 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 who's data contains the hash of the kzg commit of the blob, which is
-// dispersed separately.
message BlobHeader {
// Blob version
uint32 version = 1;
@@ -18,7 +14,7 @@ message BlobHeader {
// - 0: ETH
// - 1: EIGEN
repeated uint32 quorum_numbers = 2;
- // commitment is the KZG commitment of the blob
+ // commitment is the KZG commitment to the blob
common.BlobCommitment commitment = 3;
// payment_header contains payment information for the blob
common.PaymentHeader payment_header = 4;
@@ -29,7 +25,7 @@ message BlobHeader {
// BlobCertificate is what gets attested by the network.
// It gets constructed by the Disperser to which the DisperseBlob request was submitted.
message BlobCertificate {
- // blob_header contains metadata about the blob. The hash of this header is used to compute the blob key.
+ // blob_header contains metadata about the blob.
BlobHeader blob_header = 1;
// relays is the list of relays that are in custody of the blob.
// The relays custodying the data are chosen by the Disperser to which the DisperseBlob request was submitted.
diff --git a/api/proto/disperser/v2/disperser_v2.proto b/api/proto/disperser/v2/disperser_v2.proto
index fbe009333..771d6eafe 100644
--- a/api/proto/disperser/v2/disperser_v2.proto
+++ b/api/proto/disperser/v2/disperser_v2.proto
@@ -37,6 +37,11 @@ message DisperseBlobRequest {
// If any one of the 32 bytes elements is outside the range, the whole request is deemed as invalid, and rejected.
bytes data = 1;
// 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.
common.v2.BlobHeader blob_header = 2;
}
@@ -48,8 +53,11 @@ message DisperseBlobReply {
//
// 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 disperser.
+ // 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).
bytes blob_key = 2;
}
@@ -85,7 +93,7 @@ message BlobCommitmentReply {
// GetPaymentStateRequest contains parameters to query the payment state of an account.
message GetPaymentStateRequest {
- // The ID of the account being queried.
+ // The ID of the account being queried. This account ID is an eth wallet address of the user.
string account_id = 1;
// Signature over the account ID
// TODO: sign over a reservation period or a nonce to mitigate signature replay attacks
@@ -115,13 +123,16 @@ message GetPaymentStateReply {
// - QUEUED
// - ENCODED
// Terminal states are states that will not be updated to a different state:
+// - UNKNOWN
// - CERTIFIED
// - FAILED
// - INSUFFICIENT_SIGNATURES
-// - UNKNOWN
enum BlobStatus {
// 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.
UNKNOWN = 0;
// QUEUED means that the blob has been queued by the disperser for processing.
@@ -135,10 +146,14 @@ enum BlobStatus {
// CERTIFIED means the blob has been dispersed and attested by the DA nodes.
CERTIFIED = 3;
- // FAILED means that the blob has failed permanently.
+ // 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 with different salt (blob key is required to be unique).
FAILED = 4;
// INSUFFICIENT_SIGNATURES means that the blob has failed to gather sufficient attestation.
+ //
+ // This status is functionally equivalent to FAILED, but is used to indicate that the failure is due to an
+ // an inability to gather sufficient signatures.
INSUFFICIENT_SIGNATURES = 5;
}
diff --git a/api/proto/node/v2/node_v2.proto b/api/proto/node/v2/node_v2.proto
index bb2dc9fb3..723808942 100644
--- a/api/proto/node/v2/node_v2.proto
+++ b/api/proto/node/v2/node_v2.proto
@@ -6,15 +6,15 @@ option go_package = "github.com/Layr-Labs/eigenda/api/grpc/node/v2";
// The EigenDA Node implements two services, Dispersal and Retrieval, as defined below,
// for better security and separation of concerns.
-// Dispersal is utilized to disperse chunk data. The disperser calls these RPCs to store chunks on individual DA nodes.
+// Dispersal is utilized to disperse chunk data.
service Dispersal {
// StoreChunks stores a batch of chunks on the Node.
rpc StoreChunks(StoreChunksRequest) returns (StoreChunksReply) {}
- // NodeInfo fetches metadata about the node.
+ // GetNodeInfo fetches metadata about the node.
rpc GetNodeInfo(GetNodeInfoRequest) returns (GetNodeInfoReply) {}
}
-// Retrieval is utilized to retrieve chunk data. This chunk data can be used to reconstruct the original blob.
+// Retrieval is utilized to retrieve chunk data.
service Retrieval {
// GetChunks retrieves the chunks for a blob custodied at the Node. Note that where possible, it is generally
// faster to retrieve chunks from the relay service if that service is available.
@@ -87,7 +87,7 @@ message GetChunksReply {
repeated bytes chunks = 1;
}
-// The parameter for the NodeInfo() RPC.
+// The parameter for the GetNodeInfo() RPC.
message GetNodeInfoRequest {
}