From aa44ce786b3455297194b9ad41d149ea27ce500f Mon Sep 17 00:00:00 2001
From: Vlad <13818348+walldiss@users.noreply.github.com>
Date: Mon, 13 Jan 2025 13:36:09 +0100
Subject: [PATCH] canonical api draft

---
 api/V1/blob_service.proto  | 100 +++++++++++++
 api/V1/common.proto        |  41 ++++++
 api/V1/fraud_service.proto |  46 ++++++
 api/V1/proof_service.proto |  69 +++++++++
 api/V1/proofs.proto        |  39 ++++++
 api/V1/readme.md           | 279 +++++++++++++++++++++++++++++++++++++
 api/V1/share_service.proto | 120 ++++++++++++++++
 api/V1/types.proto         |  43 ++++++
 8 files changed, 737 insertions(+)
 create mode 100644 api/V1/blob_service.proto
 create mode 100644 api/V1/common.proto
 create mode 100644 api/V1/fraud_service.proto
 create mode 100644 api/V1/proof_service.proto
 create mode 100644 api/V1/proofs.proto
 create mode 100644 api/V1/readme.md
 create mode 100644 api/V1/share_service.proto
 create mode 100644 api/V1/types.proto

diff --git a/api/V1/blob_service.proto b/api/V1/blob_service.proto
new file mode 100644
index 0000000000..4afa40e803
--- /dev/null
+++ b/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);
+}
\ No newline at end of file
diff --git a/api/V1/common.proto b/api/V1/common.proto
new file mode 100644
index 0000000000..6398af8667
--- /dev/null
+++ b/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;
+}
\ No newline at end of file
diff --git a/api/V1/fraud_service.proto b/api/V1/fraud_service.proto
new file mode 100644
index 0000000000..442af246ae
--- /dev/null
+++ b/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);
+}
\ No newline at end of file
diff --git a/api/V1/proof_service.proto b/api/V1/proof_service.proto
new file mode 100644
index 0000000000..dd844b69a2
--- /dev/null
+++ b/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);
+}
\ No newline at end of file
diff --git a/api/V1/proofs.proto b/api/V1/proofs.proto
new file mode 100644
index 0000000000..360a7d18d4
--- /dev/null
+++ b/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;
+}
\ No newline at end of file
diff --git a/api/V1/readme.md b/api/V1/readme.md
new file mode 100644
index 0000000000..ec611a304c
--- /dev/null
+++ b/api/V1/readme.md
@@ -0,0 +1,279 @@
+# Celestia Node gRPC API Design Decisions & Motivations
+
+## Introduction
+
+This document outlines the design decisions and motivations behind the new gRPC-based API for Celestia Node. It represents an initial draft of the API design, with a focus on security, simplicity, and developer experience.
+
+### Document Purpose and Scope
+
+This document serves multiple purposes:
+- Explains the reasoning behind key architectural decisions
+- Documents the design principles guiding the API development
+- Provides context for the protocol buffer definitions
+- May serve as a foundation for a future Architecture Decision Record (ADR) in celestia-node
+
+### Important Notes for Readers
+
+1. **Complementary Documentation**:
+  - This document should be read alongside the proto files which contain the detailed API specifications
+  - The proto definitions include additional technical details and comments that complement this design overview
+
+2. **Current Status**:
+  - This is a first draft and will need further refinement and community feedback
+  - Some design decisions may evolve as we gather more implementation experience
+  - Sections marked with "TBD" indicate areas needing further discussion
+
+3. **Implementation Context**:
+  - The design primarily considers the celestia-go-node implementation as it's currently the main reference
+  - However, the API is designed with language-agnostic principles to support future implementations (e.g., Rust)
+  - Special attention is paid to security considerations and ease of correct implementation
+
+The following sections detail specific design decisions and their rationales, starting with core design philosophy and moving to service-specific considerations.
+
+[Rest of document follows...]
+
+## Core Design
+
+### 1. API Simplification & User Experience
+The API was redesigned with a strong focus on developer experience, while keeping core functionality and security:
+
+- **Security**: Ensuring proper data availability verification and proof checking
+- **Separation of Concerns**: Each service handles a specific domain (blobs, shares, proofs) rather than having monolithic endpoints. This makes the API more intuitive and easier to learn.
+- **Minimal Surface Area**: The API provides essential operations without trying to solve every edge case in a single RPC call. This approach:
+    - Makes the API easier to understand and maintain
+    - Encourages composability of basic operations
+    - Reduces complexity of individual endpoints
+
+### 2. Protocol Independence
+A key design goal was to abstract away protocol-specific details:
+
+- **Removal of DAH Dependencies**: The API minimizes reliance on DataAvailabilityHeader (DAH) to:
+    - Reduce coupling to protocol internals
+    - Make the API more stable against protocol changes
+    - Simplify client implementations
+- **Data Root Proofs Focus**: Moving towards data root proofs instead of row roots because:
+    - Provides a more direct verification path
+    - Reduces complexity of proof verification
+    - Better aligns with future protocol optimizations
+- **Easier Migration**: Across all services, some requests and responses have V0/V1 suffixes. V0 supports row root-based proofs (matching our current implementation), while V1 uses data root verification. Both options are included to enable a smoother migration to the new API while data root proofs are still under development.
+
+### 3. Data Availability
+
+Data availability verification is fundamental to light node security and must be enforced rigorously through the API. The current implementation has two key limitations:
+1. No straightforward mechanism to verify data availability at a given height
+2. ShareAvailable API only verifies individual blocks, while proper DAS verification requires checking the entire sampling window preceding the requested height
+
+Proposed Solutions:
+
+1. **Enhanced ShareAvailable Verification**:
+   The ShareAvailable call will verify the continuous chain of blocks from the oldest block in the availability window up to the requested height. The call will return false if any block within this range is unavailable.
+
+2. **Integrated Availability Verification**:
+   A new `verify_available` option will be added to all data fetching methods (blobs, shares, etc). When enabled:
+  - The API will verify availability for both the requested block and all preceding blocks within the sampling window
+  - Data will only be returned if the entire chain segment is verified as available
+  - Failed availability checks will return a specific `data_not_available` error code
+
+```protobuf
+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;
+}
+```
+
+### 4. Error Response Structure
+```protobuf
+message Status {
+    StatusCode code = 1;
+    string message = 2;
+}
+```
+
+Advantages:
+- Consistent error reporting
+- Rich error information
+- Easy to extend
+- Supports both technical and user-friendly messages
+
+Some error codes already listed in the draft, however the list might be not full and would need to be revisited with each particular usecase in mind
+
+Standardized Status Codes
+```protobuf
+// 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;
+}
+```
+
+## Service-Specific Decisions
+
+### BlobService
+
+#### 1. Data Submission Approach
+Two options were considered for blob submission:
+```protobuf
+message SubmitDataRequest {
+    bytes namespace = 1;
+    repeated bytes data = 2;
+    SubmitOptions options = 3;
+}
+
+message SubmitBlobRequest {
+  repeated Blob blobs = 1;
+  SubmitOptions options = 2;
+}
+```
+
+Chose raw data submission over pre-constructed blobs because:
+- Simpler for users - they don't need to understand blob internals
+- Reduces client-side complexity
+- Better separation between data and protocol details
+
+#### 2. Subscription Support
+Prevoiusly only one subscription endpoint existed to subscribe to all blobs from same namespace.
+```protobuf
+rpc SubscribeAll(SubscribeAllRequest) returns (stream SubscribeAllResponse);
+```
+Added new subscription endpoint `SubscribeBlobs`, which allows to subscribe for blobs by commitments:
+```protobuf
+rpc SubscribeBlobs(BlobsSubscribeRequest) returns (stream BlobsSubscribeResponse);
+```
+
+Motivations:
+- Essential for async submission workflows.It allows subscribing to blobs submitted in async mode
+- Enables event-driven architectures. 
+- Better for monitoring submitted data
+- Reduces polling overhead
+
+
+### ShareService
+Has support for requesting all common sets of shares:
+```protobuf
+// ShareService - handles data share operations
+service ShareService {
+  // Core share operations
+  rpc GetShare(GetShareRequest) returns (GetShareResponse);
+  rpc GetEDS(GetEDSRequest) returns (GetEDSResponse);
+
+  // Range operations - support both V0 (row roots) and V1 (data root) responses
+  rpc GetRange(GetRangeRequest) returns (GetRangeResponseV0);
+  rpc GetRow(GetRowRequest) returns (GetRowResponseV0);
+
+  // Namespace operations - support both verification approaches
+  rpc GetSharesByNamespace(GetSharesByNamespaceRequest) returns (GetSharesByNamespaceResponseV0);
+
+  // Availability check
+  rpc SharesAvailable(SharesAvailableRequest) returns (SharesAvailableResponse);
+}
+```
+
+`SharesAvailable` is reworked. Previously it was ensuring availability of single height. However availability of single height does not give availability gurantees. New version must ensure availability of range of height starting oldest block within availability window to the requested height. `sampling_window` option will allow users to specify smaller range verification. 
+```protobuf
+message SharesAvailableRequest {
+  uint64 height = 1;
+  optional uint32 sampling_window = 2;  // Blocks to check from height
+}
+
+message SharesAvailableResponse {
+  celestia.node.v1.common.Status status = 1;
+  bool is_available = 2;
+  uint64 highest_available_height = 3;
+}
+```
+
+Benefits:
+- More efficient than requesting individual shares
+- Better matches common usage patterns
+- Reduces number of RPC calls needed
+- Enables bulk operations with proofs
+
+### ProofsService
+
+#### 1. Dual Verification Approaches
+Accross all servecies some requests and response have V0/V1 suffix. Support both V0 (row roots) and V1 (data root) verification:
+```protobuf
+service ProofsService {
+    rpc VerifySharesV0(VerifySharesRequestV0) returns (VerifyProofResponse);
+    rpc VerifyDataProof(VerifyDataRequest) returns (VerifyProofResponse);
+}
+```
+
+Rationale:
+- Enables gradual migration to data root proofs
+- Maintains backward compatibility
+- Allows clients to choose optimal approach
+- Supports different verification needs
+
+#### 2. Proof Type Separation
+Clear separation between proof types. Allows explicit distinguishing between inclusion and non-inclusion proofs. Blob commitment proof is identified as well. ProofType also allows proof service know how to verify provided proof:
+```protobuf
+enum ProofType {
+  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;
+}
+```
+
+Benefits:
+- Clear distinction between use cases
+- Better type safety
+- Explicit about proof capabilities
+- Easier to extend with new proof types
+
+## Future Considerations
+
+### 1. Proof Evolution
+The API is designed to evolve with proof systems:
+- Easy to add new proof types
+- Clean migration paths
+- Support for ZK proofs in future
+- Flexible verification approaches
+
+### 2. Extensibility
+The design enables future extensions:
+- New service types can be added. For example for different types of fraud proofs.
+- Backward compatibility maintained by following proto guidelines. However, backwards compatability tests should be implemented for API implementation. 
+- Clear versioning for API will allow easier migration of clients.
+
+## Implementation Guidelines
+
+### 1. Native Libraries
+The API is designed to work with native libraries:
+- Core operations in protobuf
+- Complex operations in native code
+- Clear boundaries between RPC and local processing
+- Efficient data handling
+
+### 2. Client Implementation
+Recommendations for clients:
+- Use native lobs for proof verification when possible
+- Implement efficient subscription handling. (resubscription, error handling...)
+- Start with support of V0, but keep V1 proofs in mind for future.
+- Handle availability checking appropriately
+
+This design creates a foundation for building robust, efficient clients while maintaining flexibility for future protocol evolution.
\ No newline at end of file
diff --git a/api/V1/share_service.proto b/api/V1/share_service.proto
new file mode 100644
index 0000000000..e706f2d8ca
--- /dev/null
+++ b/api/V1/share_service.proto
@@ -0,0 +1,120 @@
+syntax = "proto3";
+
+package celestia.node.v1.share;
+
+option go_package = "github.com/celestiaorg/celestia-node/api/v1/share";
+
+import "common.proto";
+import "types.proto";
+import "proof.proto";
+
+message GetShareRequest {
+  uint64 height = 1;
+  uint32 row = 2;
+  uint32 col = 3;
+  optional celestia.node.v1.common.Options options = 4;
+}
+
+message GetShareResponse {
+  celestia.node.v1.common.Status status = 1;
+  optional celestia.node.v1.types.Share share = 2;
+  celestia.node.v1.proof.DataRootProof proof = 3;
+}
+
+message GetEDSRequest {
+  uint64 height = 1;
+  optional celestia.node.v1.common.Options options = 2;
+}
+
+message GetEDSResponse {
+  celestia.node.v1.common.Status status = 1;
+  repeated celestia.node.v1.types.Share shares = 2;
+}
+
+message GetRangeRequest {
+  uint64 height = 1;
+  celestia.node.v1.types.SquareRange range = 2;
+  optional celestia.node.v1.common.Options options = 3;
+}
+
+// V0 responses use row roots from DAH for verification
+message GetRangeResponseV0 {
+  celestia.node.v1.common.Status status = 1;
+  // Each row includes its proof to row root
+  repeated celestia.node.v1.types.SharesWithProof rows = 2;
+}
+
+// V1 responses use data root proofs directly
+message GetRangeResponseV1 {
+  celestia.node.v1.common.Status status = 1;
+  repeated celestia.node.v1.types.Share shares = 2;
+  celestia.node.v1.proof.DataRootProof proof = 3;  // Single proof for all shares
+}
+
+message GetRowRequest {
+  uint64 height = 1;
+  uint32 row = 2;
+  optional celestia.node.v1.common.Options options = 3;
+}
+
+// Row responses follow same V0/V1 pattern
+message GetRowResponseV0 {
+  celestia.node.v1.common.Status status = 1;
+  repeated celestia.node.v1.types.Share shares = 2;
+}
+
+message GetRowResponseV1 {
+  celestia.node.v1.common.Status status = 1;
+  repeated celestia.node.v1.types.Share shares = 2;
+  celestia.node.v1.proof.DataRootProof proof = 3;  // Requires proof to data root to prove shares are valid
+}
+
+message GetSharesByNamespaceRequest {
+  uint64 height = 1;
+  bytes namespace = 2;
+  optional celestia.node.v1.common.Options options = 3;
+}
+
+// V0: Namespace shares verified against row roots
+message GetSharesByNamespaceResponseV0 {
+  celestia.node.v1.common.Status status = 1;
+  // Each row includes its proof to row root
+  repeated celestia.node.v1.types.SharesWithProof rows = 2;
+  celestia.node.v1.types.SquareRange range = 3;
+}
+
+// V1: Namespace shares verified against data root
+message GetSharesByNamespaceResponseV1 {
+  celestia.node.v1.common.Status status = 1;
+  repeated celestia.node.v1.types.Share shares = 2;
+  celestia.node.v1.proof.DataRootProof proof = 3;
+  celestia.node.v1.types.SquareRange range = 4;
+}
+
+message SharesAvailableRequest {
+  uint64 height = 1;
+  optional uint32 sampling_window = 2;  // Blocks to check from height
+}
+
+message SharesAvailableResponse {
+  celestia.node.v1.common.Status status = 1;
+  bool is_available = 2;
+  uint64 highest_available_height = 3;
+}
+
+// ShareService - handles data share operations
+service ShareService {
+  // Core share operations
+  rpc GetShare(GetShareRequest) returns (GetShareResponse);
+  rpc GetEDS(GetEDSRequest) returns (GetEDSResponse);
+
+  // Range operations - support both V0 (row roots) and V1 (data root) responses
+  rpc GetRange(GetRangeRequest) returns (GetRangeResponseV0);
+  rpc GetRow(GetRowRequest) returns (GetRowResponseV0);
+
+  // Namespace operations - support both verification approaches
+  rpc GetSharesByNamespace(GetSharesByNamespaceRequest) returns (GetSharesByNamespaceResponseV0);
+
+  // Availability check
+  rpc SharesAvailable(SharesAvailableRequest) returns (SharesAvailableResponse);
+}
\ No newline at end of file
diff --git a/api/V1/types.proto b/api/V1/types.proto
new file mode 100644
index 0000000000..7cf97823a5
--- /dev/null
+++ b/api/V1/types.proto
@@ -0,0 +1,43 @@
+syntax = "proto3";
+
+package celestia.node.v1.types;
+
+option go_package = "github.com/celestiaorg/celestia-node/api/v1/types";
+
+import "common.proto";
+import "proof.proto";
+
+// Core data types
+message Share {
+  bytes data = 1;
+}
+
+message SquareRange {
+  uint32 start = 1;
+  uint32 end = 2;
+}
+
+message Blob {
+  bytes data = 1;
+  optional bytes signer = 2;
+  bytes commitment = 3;
+}
+
+message BlobWithProofV0 {
+  optional celestia.node.v1.types.Blob blob = 1;
+  repeated celestia.node.v1.proof.RowRootProof row_proofs = 2;
+  uint64 index = 3;  // index of the first share of the blob in the EDS
+}
+
+message BlobWithProofV1 {
+  optional celestia.node.v1.types.Blob blob = 1;
+  celestia.node.v1.proof.DataRootProof proof = 2;
+  uint64 index = 3;  // index of the first share of the blob in the EDS
+}
+
+// SharesWithProof is used in V0 verification approach with row roots
+message SharesWithProof {
+  // Shares should be from the same row
+  repeated celestia.node.v1.types.Share shares = 1;
+  celestia.node.v1.proof.RowRootProof row_proof = 2;      // NMT proof to the row root
+}
\ No newline at end of file