syntax = "proto3";

option go_package = "github.com/0glabs/0g-da-client/api/grpc/disperser";
package disperser;

// Disperser defines the public APIs for dispersing blobs.
service Disperser {
	// This API accepts blob to disperse from clients.
	// This executes the dispersal async, i.e. it returns once the request
	// is accepted. The client could use GetBlobStatus() API to poll the the
	// processing status of the blob.
	rpc DisperseBlob(DisperseBlobRequest) returns (DisperseBlobReply) {}

	// This API is meant to be polled for the blob status.
	rpc GetBlobStatus(BlobStatusRequest) returns (BlobStatusReply) {}

	// This retrieves the requested blob from the Disperser's backend.
	// The blob should have been initially dispersed via this Disperser service
	// for this API to work.
	rpc RetrieveBlob(RetrieveBlobRequest) returns (RetrieveBlobReply) {}
}

// Requests and Responses

message DisperseBlobRequest {
	// The data to be dispersed.
	// The size of data must be <= 31744 KiB.
	bytes data = 1;
}

message DisperseBlobReply {
	// The status of the blob associated with the request_id.
	BlobStatus result = 1;
	// The request ID generated by the disperser.
	// Once a request is accepted (although not processed), a unique request ID will be
	// generated.
	// Two different DisperseBlobRequests (determined by the hash of the DisperseBlobRequest)
	// will have different IDs, and the same DisperseBlobRequest sent repeatedly at different
	// times will also have different IDs.
	// The client should use this ID to query the processing status of the request (via
	// the GetBlobStatus API).
	bytes request_id = 2;
}

// BlobStatusRequest is used to query the status of a blob.
message BlobStatusRequest {
	bytes request_id = 1;
}

message BlobStatusReply {
	// The status of the blob.
	BlobStatus status = 1;
	// The blob info needed for clients to confirm the blob against the ZGDA contracts.
	BlobInfo info = 2;
}

// RetrieveBlobRequest contains parameters to retrieve the blob.
message RetrieveBlobRequest {
	// The storage hash of data
	bytes storage_root = 1;
	// This identifies the epoch that this blob belongs to.
	uint64 epoch = 2;
	// Which quorum of the blob this is requesting for.
	uint64 quorum_id = 3;
}

// RetrieveBlobReply contains the retrieved blob data
message RetrieveBlobReply {
	bytes data = 1;
}

// Data Types

enum BlobStatus {
	UNKNOWN = 0;

	// Intermediate states

	// PROCESSING means that the blob is currently being processed by the disperser
	PROCESSING = 1;
	// CONFIRMED means that the blob has been dispersed to DA Nodes and the dispersed
	// batch containing the blob has been confirmed onchain
	CONFIRMED = 2;

	// Terminal states

	// FAILED means that the blob has failed permanently (for reasons other than insufficient
	// signatures, which is a separate state)
	FAILED = 3;
	// FINALIZED means that the block containing the blob's confirmation transaction has been finalized on Ethereum
	FINALIZED = 4;
	// INSUFFICIENT_SIGNATURES means that the quorum threshold for the blob was not met
	// for at least one quorum.
	INSUFFICIENT_SIGNATURES = 5;
}

// Types below correspond to the types necessary to verify a blob
// https://github.com/0glabs/0g-da-client/blob/master/contracts/src/libraries/ZGDABlobUtils.sol#L29

// BlobInfo contains information needed to confirm the blob against the ZGDA contracts
message BlobInfo {
	BlobHeader blob_header = 1;
}

message BlobHeader {
	// The data merkle root
	bytes storage_root = 1;
	// Signers epoch
	uint64 epoch = 2;
	// Signers quorum id
	uint64 quorum_id = 3;
}