feat: gRPC proto files

Author: bingyanglin

crates/iota-grpc-client/src/event.rs

@@ -3,7 +3,7 @@
 
 use anyhow::anyhow;
 use futures::{Stream, StreamExt};
-use iota_grpc_types::v0::events as grpc_events;
+use iota_grpc_types::v0::{common as grpc_common, events as grpc_events};
 use iota_json_rpc_types::{BcsEvent, IotaEvent};
 use iota_types::{
     base_types::{IotaAddress, ObjectID, TransactionDigest},
@@ -55,7 +55,7 @@ impl EventClient {
     }
 
     /// Deserialize event data from BCS bytes.
-    fn deserialize_event(event: &grpc_events::Event) -> anyhow::Result<IotaEvent> {
+    fn deserialize_event(event: &grpc_common::Event) -> anyhow::Result<IotaEvent> {
         let event_id = event
             .event_id
             .as_ref()
@@ -76,20 +76,24 @@ impl EventClient {
             .as_ref()
             .ok_or_else(|| anyhow!("Missing sender"))?;
 
-        let bcs_data = event
+        let bcs_wrapper = event
             .event_data
             .as_ref()
             .ok_or_else(|| anyhow!("Missing event data"))?;
 
+        let bcs_data = bcs_wrapper
+            .value
+            .as_ref()
+            .ok_or_else(|| anyhow!("Missing BCS data value"))?;
+
         // Parse the StructTag from string
         let type_tag: StructTag = event
             .type_name
             .parse()
             .map_err(|e| anyhow!("Failed to parse type tag: {e}"))?;
 
-        // Parse the JSON
-        let parsed_json: serde_json::Value = serde_json::from_str(&event.parsed_json)
-            .map_err(|e| anyhow!("Failed to parse JSON: {e}"))?;
+        // We only provide BCS data; parsed_json is left empty for now
+        let parsed_json = serde_json::json!({});
 
         Ok(IotaEvent {
             id: EventID {

crates/iota-grpc-server/src/event_service.rs

@@ -40,7 +40,7 @@ impl EventGrpcService {
 #[tonic::async_trait]
 impl grpc_events::event_service_server::EventService for EventGrpcService {
     type StreamEventsStream =
-        std::pin::Pin<Box<dyn futures::Stream<Item = Result<grpc_events::Event, Status>> + Send>>;
+        std::pin::Pin<Box<dyn futures::Stream<Item = Result<grpc_common::Event, Status>> + Send>>;
 
     async fn stream_events(
         &self,
@@ -82,7 +82,7 @@ impl grpc_events::event_service_server::EventService for EventGrpcService {
                         );
 
                         // Convert to protobuf Event
-                        let proto_event = grpc_events::Event::from(&event);
+                        let proto_event = grpc_common::Event::from(&event);
 
                         yield proto_event;
                     }
@@ -106,7 +106,7 @@ fn create_event_filter(proto_filter: &grpc_events::EventFilter) -> Result<EventF
     match &proto_filter.filter {
         Some(Filter::All(_)) => Ok(EventFilter::All(vec![])),
         Some(Filter::Sender(f)) => {
-            let sender = parse_iota_address(&f.sender, "Sender address")?;
+            let sender = parse_iota_address(&f.address, "Sender address")?;
             Ok(EventFilter::Sender(sender))
         }
         Some(Filter::Transaction(f)) => {
@@ -174,7 +174,7 @@ fn parse_iota_address(
 }
 
 fn parse_tx_digest(
-    digest: &Option<grpc_common::TransactionDigest>,
+    digest: &Option<grpc_common::Digest>,
     field_name: &str,
 ) -> Result<TransactionDigest, Status> {
     let digest = digest

crates/iota-grpc-server/tests/event_e2e.rs

@@ -21,11 +21,6 @@ const CLOCK_ACCESS_FUNCTION: &str = "access";
 // Event type names
 const NFT_MINTED_EVENT: &str = "NFTMinted";
 
-// JSON field names for event validation
-const OBJECT_ID_FIELD: &str = "object_id";
-const CREATOR_FIELD: &str = "creator";
-const NAME_FIELD: &str = "name";
-
 async fn setup_test_cluster() -> (TestCluster, EventClient, ObjectID, ObjectID) {
     let localhost = local_ip_utils::localhost_for_testing();
     let grpc_port = local_ip_utils::get_available_port(&localhost);
@@ -102,7 +97,7 @@ async fn test_event_filtering_and_bcs_serialization() {
     // Client 1: AllFilter - should receive all events
     let mut all_client = event_client.clone();
     let all_filter = grpc_events::EventFilter {
-        filter: Some(Filter::All(grpc_events::AllFilter {})),
+        filter: Some(Filter::All(grpc_common::AllFilter {})),
     };
     let mut all_stream = all_client
         .stream_events(all_filter)
@@ -112,8 +107,8 @@ async fn test_event_filtering_and_bcs_serialization() {
     // Client 2: SenderFilter - should receive only events from sender_1
     let mut sender_client = event_client.clone();
     let sender_filter = grpc_events::EventFilter {
-        filter: Some(Filter::Sender(grpc_events::SenderFilter {
-            sender: Some(grpc_common::Address {
+        filter: Some(Filter::Sender(grpc_common::AddressFilter {
+            address: Some(grpc_common::Address {
                 address: sender_1.to_vec(),
             }),
         })),
@@ -126,7 +121,7 @@ async fn test_event_filtering_and_bcs_serialization() {
     // Client 3: MoveEventTypeFilter - should receive only NFT events
     let mut nft_client = event_client.clone();
     let nft_filter = grpc_events::EventFilter {
-        filter: Some(Filter::MoveEventType(grpc_events::MoveEventTypeFilter {
+        filter: Some(Filter::MoveEventType(grpc_common::MoveEventTypeFilter {
             package_id: Some(grpc_common::Address {
                 address: nft_package_id.to_vec(),
             }),
@@ -272,12 +267,6 @@ async fn test_event_filtering_and_bcs_serialization() {
                         );
                         assert!(!event.bcs.bytes().is_empty(), "BCS data must be valid");
 
-                        // Verify JSON structure for BCS deserialization
-                        let parsed_json = &event.parsed_json;
-                        assert!(parsed_json.get(OBJECT_ID_FIELD).is_some());
-                        assert!(parsed_json.get(CREATOR_FIELD).is_some());
-                        assert!(parsed_json.get(NAME_FIELD).is_some());
-
                         nft_events.push(event);
 
                         if nft_events.len() >= 3 {

crates/iota-grpc-types/proto/iota/grpc/v0/coin.proto

@@ -0,0 +1,111 @@
+// Copyright (c) 2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package iota.grpc.v0.coin;
+
+import "common.proto";
+
+// Coin service provides access to coin-related data such as coins owned by an
+// address, balances, and coin metadata.
+service CoinService {
+  // Get coins of a specific type owned by an address
+  rpc GetCoins (GetCoinsRequest) returns (GetCoinsResponse);
+
+  // Get all coins owned by an address (all coin types)
+  rpc GetAllCoins (GetAllCoinsRequest) returns (GetAllCoinsResponse);
+
+  // Get balance for a specific coin type
+  rpc GetBalance (GetBalanceRequest) returns (GetBalanceResponse);
+
+  // Get all balances across all coin types
+  rpc GetAllBalances (GetAllBalancesRequest) returns (GetAllBalancesResponse);
+
+  // Get coin metadata
+  rpc GetCoinMetadata (GetCoinMetadataRequest) returns (GetCoinMetadataResponse);
+}
+
+message GetCoinsRequest {
+  // The owner's IOTA address
+  iota.grpc.v0.common.Address owner = 1;
+
+  // Optional type name for the coin (e.g., 0x2::iota::IOTA)
+  // Defaults to "0x2::iota::IOTA" if not specified
+  optional string coin_type = 2;
+
+  // The maximum number of items to return per page
+  // Default: 50, Max: 1000
+  optional uint32 page_size = 3;
+
+  // Opaque pagination token from previous response
+  // Token is BCS-encoded and should be treated as opaque by clients
+  optional iota.grpc.v0.common.BcsData page_token = 4;
+}
+
+message GetCoinsResponse {
+  // List of coin objects
+  repeated iota.grpc.v0.common.CoinInfo data = 1;
+
+  // Token for next page. If omitted, no more pages exist.
+  // This is an opaque BCS-encoded token
+  optional iota.grpc.v0.common.Bcs next_page_token = 2;
+}
+
+message GetAllCoinsRequest {
+  // The owner's IOTA address
+  iota.grpc.v0.common.Address owner = 1;
+
+  // The maximum number of items to return per page
+  // Default: 50, Max: 1000
+  optional uint32 page_size = 2;
+
+  // Opaque pagination token from previous response
+  // Token is BCS-encoded and should be treated as opaque by clients
+  optional iota.grpc.v0.common.BcsData page_token = 3;
+}
+
+message GetAllCoinsResponse {
+  // List of coin objects
+  repeated iota.grpc.v0.common.CoinInfo data = 1;
+
+  // Token for next page. If omitted, no more pages exist.
+  // This is an opaque BCS-encoded token
+  optional iota.grpc.v0.common.Bcs next_page_token = 2;
+}
+
+// GetBalance - Return the total coin balance for one coin type
+message GetBalanceRequest {
+  // The owner's IOTA address
+  iota.grpc.v0.common.Address owner = 1;
+
+  // Optional type name for the coin (e.g., 0x2::iota::IOTA)
+  // Defaults to "0x2::iota::IOTA" if not specified
+  optional string coin_type = 2;
+}
+
+message GetBalanceResponse {
+  iota.grpc.v0.common.BalanceInfo balances = 1;
+}
+
+// GetAllBalances - Return the total coin balance for all coin types
+message GetAllBalancesRequest {
+  // The owner's IOTA address
+  iota.grpc.v0.common.Address owner = 1;
+}
+
+message GetAllBalancesResponse {
+  // List of balances for all coin types
+  repeated iota.grpc.v0.common.BalanceInfo balances = 1;
+}
+
+// GetCoinMetadata - Return metadata for a coin
+message GetCoinMetadataRequest {
+  // Type name for the coin (e.g., 0x2::iota::IOTA)
+  string coin_type = 1;
+}
+
+message GetCoinMetadataResponse {
+  // BCS-encoded iota_types::coin::CoinMetadata
+  optional iota.grpc.v0.common.Bcs metadata = 1;
+}