(Discussion): canonical api draft

api/V1/blob_service.proto

@@ -0,0 +1,100 @@
+syntax = "proto3";
+
+package celestia.node.v1.blob;
+
+option go_package = "github.com/celestiaorg/celestia-node/api/v1/blob";
+
+import "common.proto";
+import "types.proto";
+import "proof.proto";
+
+message SubmitOptions {
+  double gas_price = 1;    // Amount to be paid per gas unit
+  uint64 gas = 2;         // Gas amount
+  string key_name = 3;    // Keystore key for signing
+  optional string fee_granter = 4;  // Account paying for transaction
+  optional uint64 nonce = 5;        // Transaction nonce
+}
+
+message GetBlobRequest {
+  uint64 height = 1;
+  bytes namespace = 2;
+  bytes commitment = 3;
+  optional bool provide_commitment_proof = 4;
+  optional celestia.node.v1.common.Options options = 5;
+}
+
+message GetBlobResponseV0 {
+  celestia.node.v1.common.Status status = 1;
+  celestia.node.v1.types.BlobWithProofV0 blob = 2;
+}
+
+message GetBlobResponseV1 {
+  celestia.node.v1.common.Status status = 1;
+  celestia.node.v1.types.BlobWithProofV1 blob = 2;
+}
+
+message GetBlobsRequest {
+  uint64 height = 1;
+  bytes namespaces = 2;
+  optional celestia.node.v1.common.Options options = 3;
+}
+
+message GetBlobsResponseV0 {
+  celestia.node.v1.common.Status status = 1;
+  repeated celestia.node.v1.types.BlobWithProofV0 blobs = 2;
+}
+
+message GetBlobsResponseV1 {
+  celestia.node.v1.common.Status status = 1;
+  repeated celestia.node.v1.types.BlobWithProofV1 blobs = 2;
+}
+
+message SubmitDataRequest {
+  bytes namespace = 1;
+  repeated bytes data = 2;
+  SubmitOptions options = 3;
+}
+
+message SubmitDataResponse {
+  celestia.node.v1.common.Status status = 1;
+  uint64 height = 2;
+  repeated bytes commitments = 3;
+}
+
+message SubscribeAllRequest {
+  bytes namespaces = 1;
+  uint64 from_height = 2;
+  optional celestia.node.v1.common.Options options = 3;
+}
+
+message SubscribeAllResponse {
+  celestia.node.v1.common.Status status = 1;
+  uint64 height = 2;
+  repeated celestia.node.v1.types.BlobWithProofV1 blobs = 3;
+}
+
+message BlobsSubscribeRequest {
+  bytes namespaces = 1;
+  uint64 from_height = 2;
+  repeated bytes commitment = 3;
+  optional celestia.node.v1.common.Options options = 4;
+}
+
+message BlobsSubscribeResponse {
+  bytes commitment = 1;
+  celestia.node.v1.types.BlobWithProofV1 blob = 2;
+  uint64 height = 3;
+}
+
+// BlobService - handles blob operations
+service BlobService {
+  // Core operations
+  rpc GetBlob(GetBlobRequest) returns (GetBlobResponseV0);
+  rpc GetBlobs(GetBlobsRequest) returns (GetBlobsResponseV0);
+  rpc SubmitData(SubmitDataRequest) returns (SubmitDataResponse);
+
+  // Subscription operations
+  rpc SubscribeBlobs(BlobsSubscribeRequest) returns (stream BlobsSubscribeResponse);
+  rpc SubscribeAll(SubscribeAllRequest) returns (stream SubscribeAllResponse);
+}

api/V1/common.proto

@@ -0,0 +1,41 @@
+syntax = "proto3";
+
+package celestia.node.v1.common;
+
+option go_package = "github.com/celestiaorg/celestia-node/api/v1/common";
+
+// Common status codes used across all services
+enum StatusCode {
+  // Reserve 0 for unspecified
+  STATUS_UNSPECIFIED = 0;
+  // Success codes (1-99)
+  STATUS_OK = 1;
+  // Error codes (100+)
+  // ERROR_DATA_NOT_AVAILABLE is returned if data availability sampling gurantees was required for request
+  // and failed. Keep in mind that data availability sampling will be ensured for all blocks in
+  // sampling window till the requested height
+  ERROR_DATA_NOT_AVAILABLE = 100;
+  // Fraud was detected in the chain before requested block
+  ERROR_FRAUD_DETECTED = 101;
+  ERROR_TIMEOUT = 102;
+  // invalid input was submit as part of request. More information is provided in Status message field.
+  ERROR_INVALID_REQUEST = 103;
+  // unexpected error happened during handling the request
+  ERROR_INTERNAL = 104;
+  // method is not implemented by the server
+  ERROR_NOT_IMPLEMENTED = 105;
+}
+
+// Common message types used across services
+message Status {
+  StatusCode code = 1;
+  string message = 2;
+}
+
+message Options {
+  // if verify_available is enabled, node will additionally ensure
+  // data availability on top of fetching requiested data
+  bool verify_available = 1;
+  // when proofs_only is enabled, proofs will be returned without sending data.
+  bool proofs_only = 2;
+}

api/V1/fraud_service.proto

@@ -0,0 +1,46 @@
+syntax = "proto3";
+
+package celestia.node.v1.fraud;
+
+option go_package = "github.com/celestiaorg/celestia-node/api/v1/fraud";
+
+// BadEncodingFraudProof represents a proof of fraudulent data encoding
+message BadEncodingFraudProof {
+  uint64 height = 1;
+  // TODO: add concrete fields
+}
+
+// Request to get all Bad Encoding Fraud Proofs from a specific height
+message GetAllBEFPRequest {
+  uint64 from_height = 1;
+  uint64 max_amount = 2;  // For pagination
+}
+
+message GetAllBEFPResponse {
+  repeated BadEncodingFraudProof fraud_proofs = 1;
+}
+
+message SubscribeBEFPRequest {
+  uint64 from_height = 1;
+}
+
+message SubscribeBEFPResponse {
+  BadEncodingFraudProof fraud_proofs = 1;
+}
+
+message VerificationResponse {
+  bool valid = 1;
+  string error = 2;
+}
+
+// BadEncodingFraudProofService - handles operations related to Bad Encoding Fraud Proofs
+service BadEncodingFraudProofService {
+  // Get all fraud proofs from a specific height with pagination
+  rpc GetAll(GetAllBEFPRequest) returns (GetAllBEFPResponse);
+
+  // Subscribe to receive fraud proofs as they are discovered
+  rpc SubscribeBEFPs(SubscribeBEFPRequest) returns (stream SubscribeBEFPResponse);
+
+  // Verify a given fraud proof
+  rpc Verify(BadEncodingFraudProof) returns (VerificationResponse);
+}

api/V1/proof_service.proto

@@ -0,0 +1,69 @@
+syntax = "proto3";
+
+package celestia.node.v1.proof;
+
+option go_package = "github.com/celestiaorg/celestia-node/api/v1/proof";
+
+import "common.proto";
+import "types.proto";
+
+message VerifyDataRequest {
+  bytes root = 1;
+  bytes namespace = 2;
+  Proof proof = 3;
+  optional bytes data = 4;  // Not used for non-inclusion proofs
+}
+
+message VerifySharesRequestV0 {
+  bytes row_root = 1;
+  // Each row includes its proof to row root
+  repeated celestia.node.v1.types.SharesWithProof rows = 2;
+}
+
+message VerifySharesRequestV1 {
+  bytes root = 1;
+  repeated celestia.node.v1.types.Share shares = 2;
+  DataRootProof proof = 3;
+}
+
+message VerifyNamespaceRequestV0 {
+  repeated bytes row_roots = 1;
+  bytes namespace = 2;
+  repeated celestia.node.v1.types.SharesWithProof rows = 3;
+}
+
+message VerifyNamespaceRequestV1 {
+  bytes root = 1;
+  bytes namespace = 2;
+  repeated celestia.node.v1.types.Share shares = 3;
+  DataRootProof proof = 4;
+}
+
+message VerifyCommitmentRequest {
+  bytes root = 1;
+  bytes namespace = 2;
+  bytes commitment = 3;
+  DataRootProof proof = 4;
+}
+
+message VerifyProofResponse {
+  celestia.node.v1.common.Status status = 1;
+  bool valid = 2;
+}
+
+// ProofsService - verification service that supports both V0 and V1 approaches
+service ProofsService {
+  // V0 verification of inclusion of shares. Requires row root to perform verification.
+  // Does not verifies namespace rules of provided shares and should be used only
+  // to verify inclusion of data spread over multiple namespaces
+  rpc VerifySharesV0(VerifySharesRequestV0) returns (VerifyProofResponse);
+  // Performs what VerifySharesV0 does with additional namespace rules verification on top.
+  rpc VerifyNamespaceV0(VerifyNamespaceRequestV0) returns (VerifyProofResponse);
+
+  // V1 verification
+  // VerifyDataProof verifies raw blob data using data root proof
+  rpc VerifyDataProof(VerifyDataRequest) returns (VerifyProofResponse);
+  // VerifyCommitmentProof verifies inclusion of blob, by using commitment and commitment data root proof.
+  // Provided proof type should be PROOF_TYPE_COMMITMENT
+  rpc VerifyCommitmentProof(VerifyCommitmentRequest) returns (VerifyProofResponse);
+}

api/V1/proofs.proto

@@ -0,0 +1,39 @@
+syntax = "proto3";
+
+package celestia.node.v1.proof;
+
+option go_package = "github.com/celestiaorg/celestia-node/api/v1/proof";
+
+// Proof system supports two verification approaches:
+// 1. Row roots (V0) - Uses row roots from Data Availability Header (DAH) for verification
+// 2. Data root (V1) - Uses data root proofs directly, more efficient and doesn't require DAH
+enum ProofType {
+  PROOF_TYPE_UNSPECIFIED = 0;
+  // Data proofs
+  PROOF_TYPE_DATA_INCLUSION = 1;
+  // Contains leaf hashes for the range where namespace would be
+  PROOF_TYPE_DATA_NON_INCLUSION = 2;
+  // Commitment proof is used for blobs only.
+  // It contains first share of the blob and its inclusion proof
+  PROOF_TYPE_COMMITMENT = 3;
+  // TBD: structure for commitment non-inclusion
+  PROOF_TYPE_COMMITMENT_NON_INCLUSION = 4;
+}
+
+// Core proof structure used in both V0 (row roots) and V1 (data root) verification
+message Proof {
+  int32 start = 1;  // Start index in EDS
+  int32 end = 2;    // End index in EDS
+  repeated bytes nodes = 3;  // NMT proof nodes (48 bytes each: namespace bounds + hash)
+  bytes leaf_hash = 4;       // Used for non-inclusion proofs (40 bytes: namespace + hash)
+}
+
+message DataRootProof {
+  ProofType type = 1;
+  Proof proof = 2;
+}
+
+message RowRootProof {
+  Proof proof = 1;
+  uint64 row_index = 2;
+}