[DRAFT] canonical v1 API

assets/cip-api-v1/proto/befp/befp.proto

@@ -0,0 +1,10 @@
+syntax = "proto3";
+
+package befp;
+
+message BEFPRequest {
+  uint64 from_height = 1;
+}
+
+message BEFPsSubscribeRequest {}
+

assets/cip-api-v1/proto/befp/befp_service.proto

@@ -0,0 +1,12 @@
+syntax = "proto3";
+
+import "befp/befp.proto";
+// https://github.com/celestiaorg/celestia-node/blob/main/share/eds/byzantine/pb/share.proto
+import "befp/third_party/share.proto";
+
+package befp;
+
+service BadEncodingFraudProofService {
+  rpc GetAll(BEFPRequest) returns (share.eds.byzantine.pb.BadEncoding) {}
+  rpc SubscribeBEFPs(BEFPsSubscribeRequest) returns (stream share.eds.byzantine.pb.BadEncoding) {}
+}

assets/cip-api-v1/proto/blob/blob.proto

@@ -0,0 +1,76 @@
+syntax = "proto3";
+
+package blob;
+
+import "common/retrieval_options.proto";
+import "common/error.proto";
+import "common/tx_config.proto";
+
+message Blob {
+  bytes namespace_id = 1;
+  bytes data = 2;
+  uint32 share_version = 3;
+  bytes commitment = 4;
+  uint32 index = 5;
+  // TODO do we need namespace version in here as well?
+}
+
+message BlobRequest {
+  uint64 height = 1;
+  bytes namespace_id = 2;
+  bytes commitment = 3;
+  common.RetrievalMode retrieval_mode = 4;
+}
+
+// TODO simpler alternative?
+//message BlobResponse {
+//    Blob blob = 1;
+//    common.RpcError error = 2;
+//}
+message BlobResponse {
+  oneof response {
+    // TODO: can there always only be one unique blob?
+    // e.g. what if someone submits the same blob twice into a block?
+    // should that be indicated somehow? Or is it fine to only return one blob as nothing
+    // is gained from returning it twice/multiple times anyways.
+    Blob blob = 1;
+    common.RpcError error = 2;
+  }
+}
+
+
+message BlobList {
+  repeated Blob blobs = 1;
+}
+
+message BlobListRequest {
+  uint64 height = 1;
+  bytes namespace_id = 2;
+  common.RetrievalMode retrieval_mode = 3;
+}
+
+message BlobListResponse {
+  oneof response {
+    BlobList blob_list = 1;
+    common.RpcError error = 2;
+  }
+}
+
+message SubmitBlobRequest {
+  Blob blob = 1;
+  common.TxConfig tx_config = 2;
+}
+
+message SubmitBlobResponse {
+  bytes commitment = 1;
+  // https://github.com/celestiaorg/celestia-node/discussions/3517#discussioncomment-9838338
+  oneof identifier {
+    uint32 block_height = 2; // ID for sync blob submission.
+    bytes tx_hash = 3; // ID for async blob submission.
+  }
+  common.RpcError error = 4;
+}
+
+message SubscribeBlobByNamespaceRequest {
+  bytes namespace_id = 1;
+}

assets/cip-api-v1/proto/blob/blob_service.proto

@@ -0,0 +1,13 @@
+syntax = "proto3";
+package blob;
+
+import "blob/blob.proto";
+
+
+service BlobService {
+  rpc GetBlobByCommitment (BlobRequest) returns (BlobResponse) {}
+  rpc GetBlobs (BlobListRequest) returns (BlobListResponse) {}
+  rpc SubmitBlob (SubmitBlobRequest) returns (SubmitBlobResponse) {}
+
+  rpc Subscribe(SubscribeBlobByNamespaceRequest) returns (stream Blob) {}
+}

assets/cip-api-v1/proto/common/error.proto

@@ -0,0 +1,18 @@
+syntax = "proto3";
+
+package common;
+
+enum ErrorCode {
+  UNKNOWN_ERROR = 0;
+  INVALID_REQUEST = 1;
+  INVALID_PARAMS = 3;
+  INTERNAL_ERROR = 4;
+  // Add more specific error codes as needed
+  // https://github.com/celestiaorg/celestia-node/issues/3335#issuecomment-2079748320
+  // https://github.com/rollkit/go-da/issues/65
+}
+
+message RpcError {
+  ErrorCode code = 1;
+  string message = 2;
+}

assets/cip-api-v1/proto/common/retrieval_options.proto

@@ -0,0 +1,12 @@
+syntax = "proto3";
+
+package common;
+
+enum RetrievalMode {
+  // Retrieve both proofs and data. Default mode.
+  PROOFS_AND_DATA = 0;
+  // Retrieve only data.
+  DATA_ONLY = 1;
+  // Retrieve only proofs.
+  PROOFS_ONLY = 2;
+}

assets/cip-api-v1/proto/common/tx_config.proto

@@ -0,0 +1,10 @@
+syntax = "proto3";
+
+package common;
+
+message TxConfig {
+  optional string signer_address_or_id = 1;
+  optional float gas_price = 3;
+  optional uint64 gas = 4;
+  optional string fee_granter_address = 5;
+}

assets/cip-api-v1/proto/header/header.proto

@@ -0,0 +1,48 @@
+syntax = "proto3";
+
+package header;
+
+import "common/error.proto";
+
+message ExtendedHeader {
+  tendermint.types.Header header = 1;
+  tendermint.types.Commit commit = 2;
+  tendermint.types.ValidatorSet validator_set = 3;
+  celestia.da.DataAvailabilityHeader dah = 4;
+}
+
+message ExtendedHeaderList {
+  repeated ExtendedHeader extended_headers = 1;
+}
+
+message ExtendedHeaderRequest {
+    uint32 height = 1;
+}
+
+message HeaderRequest {
+  uint64 height = 1;
+}
+
+message HeaderResponse {
+  oneof response {
+    // returns just the plain core header:
+    tendermint.types.Header header = 1;
+    common.RpcError error = 2;
+  }
+}
+
+message HeaderSubscribeRequest {}
+
+
+message ExtendedHeaderListRequest {
+  uint32 start_block = 1;
+  uint32 end_block = 2;
+}
+
+message ExtendedHeaderResponse {
+  ExtendedHeader extended_header = 1;
+}
+
+message ExtendedHeaderListResponse {
+  ExtendedHeaderList extended_header_list = 1;
+}

assets/cip-api-v1/proto/header/header_service.proto

@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+import "header/header.proto";
+
+package header;
+
+service ExtendedHeaderService {
+  // simple "core" header related:
+  rpc GetHeaderByHeight (HeaderRequest) returns (HeaderResponse) {}
+  rpc SubscribeHeaders (HeaderSubscribeRequest) returns (stream tendermint.types.Header) {}
+
+  // extended header related:
+  rpc GetExtendedHeaderByHash (ExtendedHeaderRequest) returns (ExtendedHeaderResponse) {}
+  rpc GetExtendedHeaderByHeight (ExtendedHeaderRequest) returns (ExtendedHeaderResponse) {}
+  rpc GetExtendedHeaderListByHeights (ExtendedHeaderListRequest) returns (ExtendedHeaderListResponse) {}
+  rpc SubscribeExtendedHeaders (HeaderSubscribeRequest) returns (stream ExtendedHeader) {}
+}

assets/cip-api-v1/proto/share/share.proto

@@ -0,0 +1,53 @@
+syntax = "proto3";
+
+package share;
+
+import "common/error.proto";
+import "common/retrieval_options.proto";
+import "header/header.proto";
+
+message Share {
+  bytes namespace_id = 1;
+  bytes data = 2;
+  uint32 share_version = 3;
+  uint32 namespace_version = 4;
+  bytes commitment = 5;
+  uint32 index = 6;
+}
+
+message ShareRequest {
+  header.ExtendedHeader extended_header = 1;
+  uint32 row = 2;
+  uint32 column = 3;
+  common.RetrievalMode options = 4;
+}
+
+message ShareResponse {
+  oneof response {
+    Share share = 1;
+    common.RpcError error = 2;
+  }
+}
+
+message ShareList {
+  repeated Share shares = 1;
+}
+
+message ShareListRequest {
+  header.ExtendedHeader extended_header = 1;
+  bytes namespace_id = 2;
+  common.RetrievalMode options = 3;
+}
+
+message ShareListResponse {
+  oneof response {
+    ShareList share_list = 1;
+    common.RpcError error = 2;
+  }
+}
+
+message GetRowRequest {
+  uint64 height = 1;
+  uint32 index = 2;
+  common.RetrievalMode options = 3;
+}

assets/cip-api-v1/proto/share/share_service.proto

@@ -0,0 +1,11 @@
+syntax = "proto3";
+import "share.proto";
+
+package share;
+
+service ShareService {
+  rpc GetShareByNamespace (ShareRequest) returns (ShareResponse) {}
+  rpc GetSharesInRange (ShareRangeRequest) returns (ShareRangeResponse) {}
+  rpc GetSharesWithProof (ShareProofRequest) returns (ShareProofResponse) {}
+  rpc GetRow (GetRowRequest) returns (ShareListResponse) {}
+}