From 12776665bf58efb141bc9aac1d8e309af9e75e39 Mon Sep 17 00:00:00 2001
From: Kariy <ammr.arf@gmail.com>
Date: Fri, 1 Sep 2023 04:01:23 +0800
Subject: [PATCH] define simple protos for entity diffs subscription

---
 Cargo.lock                          |  3 ++
 crates/torii/grpc/Cargo.toml        |  3 ++
 crates/torii/grpc/proto/world.proto | 82 ++++++++++++++++++++++++++++-
 3 files changed, 86 insertions(+), 2 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 511aace833..8ec9d6d016 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -6808,7 +6808,10 @@ name = "torii-grpc"
 version = "0.2.1"
 dependencies = [
  "prost",
+ "serde_json",
  "sqlx",
+ "starknet",
+ "starknet-crypto 0.5.1",
  "tonic",
  "tonic-build",
 ]
diff --git a/crates/torii/grpc/Cargo.toml b/crates/torii/grpc/Cargo.toml
index fc62960334..2e83a4f24b 100644
--- a/crates/torii/grpc/Cargo.toml
+++ b/crates/torii/grpc/Cargo.toml
@@ -7,7 +7,10 @@ version.workspace = true
 
 [dependencies]
 prost = "0.11"
+serde_json.workspace = true
 sqlx = { version = "0.6.2", features = [ "chrono", "macros", "offline", "runtime-actix-rustls", "sqlite", "uuid" ] }
+starknet-crypto.workspace = true
+starknet.workspace = true
 tonic = "0.9"
 
 [build-dependencies]
diff --git a/crates/torii/grpc/proto/world.proto b/crates/torii/grpc/proto/world.proto
index 720a66d6d8..d310839c84 100644
--- a/crates/torii/grpc/proto/world.proto
+++ b/crates/torii/grpc/proto/world.proto
@@ -4,7 +4,17 @@ package world;
 // The World service provides information about the world.
 service World {
     // Retrieves metadata about the world.
-    rpc Meta (MetaRequest) returns (MetaReply);
+    rpc Meta (MetaRequest) returns (MetaResponse);
+    // Retrieves the component values for an entity.
+    rpc GetEntity (GetEntityRequest) returns (GetEntityResponse);
+    // Retrieves all entities of a component.
+    rpc GetEntities (GetEntitiesRequest) returns (GetEntitiesResponse);
+
+    /* 
+     * Subscribes to entity updates.
+     * Bidirectional streaming as we want to allow user to change the list of entities to subscribe to without closing the connection.
+     */
+    rpc SubscribeEntities (stream SubscribeEntitiesRequest) returns (stream SubscribeEntitiesResponse);
 }
 
 // A request to retrieve metadata for a specific world ID.
@@ -14,7 +24,7 @@ message MetaRequest {
 }
 
 // The metadata response contains addresses and class hashes for the world.
-message MetaReply {
+message MetaResponse {
     // The hex-encoded address of the world.
     string world_address = 1;
     // The hex-encoded class hash of the world.
@@ -24,3 +34,71 @@ message MetaReply {
     // The hex-encoded class hash of the executor.
     string executor_class_hash = 4;
 }
+
+// A request to retrieve a component value of an entity.
+message GetEntityRequest {
+    // The component name.
+    string component = 1;
+    // The entity keys.
+    EntityKeys keys = 2;
+}
+
+// The entity response contains the component values for the requested entities.
+message GetEntityResponse {
+    repeated string values = 1;
+}
+
+// A request to retrieve all entities of a component.
+message GetEntitiesRequest {
+    // The component name.
+    string component = 1;
+}
+
+// The entities response contains the keys of all entities for the requested component.
+message GetEntitiesResponse {
+    // The list of entities keys.
+    repeated EntityKeys keys = 1;
+}
+
+// The entity keys which is a list of hex-encoded field elements.
+message EntityKeys {
+    repeated string values = 1;
+}
+
+// The entity values which is a list of hex-encoded field elements.
+message EntityValues {
+    repeated string values = 2;
+}
+
+message SubscribeEntitiesRequest {
+    // List of entities to subscribe to.
+    repeated GetEntitiesRequest entities = 1;
+}
+
+/* 
+ * The entity diffs is a list of entity whose values have changed since the last block.
+ * The diffs are grouped by the component name.
+ */
+message EntityUpdate {
+
+    /*
+     * Map of entity keys to its component values.
+     * The key are the hex-encoded poseidon hash of the entity keys.
+     */
+    message EntityDiff {
+        map<string, EntityValues> entities = 1;
+    }
+
+    // The block hash of the update.
+    string block_hash = 1;
+    // The block number of the update.
+    string block_number = 2;
+    // Map of component names to entity diffs.
+    map<string, EntityDiff> entity_diffs = 3;
+}
+
+message SubscribeEntitiesResponse {
+    // List of entities that have been updated.
+    EntityUpdate entity_update = 1;
+}
+