From 13c0d72fc9322829f293fa2231f1b9927e2ded6f Mon Sep 17 00:00:00 2001
From: Clark Alesna <clark_alesna@hotmail.com>
Date: Thu, 5 Sep 2024 23:13:02 +0800
Subject: [PATCH] feat: add grpcurl guide (#13)

Co-authored-by: Santiago Carmuega <santiago@carmuega.me>
---
 pages/_meta.json  |   7 ++-
 pages/grpcurl.mdx | 130 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 136 insertions(+), 1 deletion(-)
 create mode 100644 pages/grpcurl.mdx

diff --git a/pages/_meta.json b/pages/_meta.json
index 9370b94..d63f195 100644
--- a/pages/_meta.json
+++ b/pages/_meta.json
@@ -39,5 +39,10 @@
   },
   "servers": "Servers",
   "clients": "Clients",
-  "teams": "Teams"
+  "teams": "Teams",
+  "-- Guides --": {
+    "type": "separator",
+    "title": "Guides"
+  },
+  "grpcurl": "Using grpcurl"
 }
diff --git a/pages/grpcurl.mdx b/pages/grpcurl.mdx
new file mode 100644
index 0000000..f7f3b4f
--- /dev/null
+++ b/pages/grpcurl.mdx
@@ -0,0 +1,130 @@
+# Using Grpcurl for Interacting with U5C
+
+## Introduction to Grpcurl
+
+Grpcurl is to gRPC what curl is to HTTP. While HTTP APIs are prevalent and familiar to most developers, gRPC is gradually gaining traction, especially for internal microservices communication due to its efficiency and performance. However, gRPC's binary protocol can make it seem less accessible, as traditional tools like curl don't work with it. Enter grpcurl - a command-line tool that brings the ease and familiarity of curl to gRPC.
+
+## Installing Grpcurl
+
+Grpcurl can be installed on various operating systems. Detailed installation instructions and binaries can be found on its official GitHub repository (https://github.com/fullstorydev/grpcurl#installation).
+
+## Connecting to a Local [Dolos](https://github.com/txpipe/dolos) Node (U5C compliant node)
+
+```sh
+grpcurl -plaintext localhost:50051 list
+```
+
+This command will list the available services on the Dolos node running locally on port 50051.
+
+## Listing Services and Methods
+
+You can list the services or describe specific methods provided by the U5C endpoint:
+
+```sh
+grpcurl -plaintext localhost:50051 list utxorpc.sync.v1.ChainSyncService
+```
+
+## Executing Request/Reply Method
+
+```sh
+grpcurl -plaintext localhost:50051 describe utxorpc.sync.v1.ChainSyncService.FetchBlock
+```
+
+This command will describe the FetchBlock method provided by the ChainSyncService. The output will be similar to the following:
+
+```sh
+utxorpc.sync.v1.ChainSyncService.FetchBlock is a method:
+rpc FetchBlock ( .utxorpc.sync.v1.FetchBlockRequest ) returns ( .utxorpc.sync.v1.FetchBlockResponse );
+```
+
+We can describe the FetchBlockRequest to see what parameters it takes:
+
+```sh
+grpcurl -plaintext localhost:50051 describe utxorpc.sync.v1.FetchBlockRequest
+```
+
+The output will be similar to the following:
+```sh
+utxorpc.sync.v1.FetchBlockRequest is a message:
+// Request to fetch a block by its reference.
+message FetchBlockRequest {
+  repeated .utxorpc.sync.v1.BlockRef ref = 1;
+  .google.protobuf.FieldMask field_mask = 2;
+}
+```
+
+Once you understand the request format, you can execute a method. For instance, fetching a specific block:
+
+```sh
+grpcurl -plaintext -d '{"ref": [{"index": 300042, "hash": "LRptYoRi+RG+TmxUmSsoB3lr6BLEQ2pLA+UWhgwgiIA="}]}' localhost:50051 utxorpc.sync.v1.ChainSyncService.FetchBlock
+```
+
+In this example the hash is the `Block` hash bytes encoded in `base64`.
+
+The output will be similar to the following:
+```json
+{
+  "block": [
+    {
+      "cardano": {
+        "header": {
+          "slot": "300042",
+          "hash": "LRptYoRi+RG+TmxUmSsoB3lr6BLEQ2pLA+UWhgwgiIA="
+        },
+        "body": {
+          "tx": [
+            {
+              "inputs": [
+                {
+                  "txHash": "KzlvndWhqG23d2GdZjia94LcRDqwk3nCodeuuRZVI0M=",
+                  "outputIndex": 1
+                },
+                {
+                  "txHash": "aUNQxBqVlZOv/hAiL8ZqhCMSmJR4ZLiKlNzzpwot66w="
+                }
+              ],
+              "outputs": [
+                {
+                  "address": "gtgYWEKDWBzE+sU/eyXZ3mt9Cbzb6HmcdZYQo+ENEiYDV/oioQFYHlgc6aRDIU6NiYGVLgPdq1GS6ZbJI5WXLL2VV3O2ngAahdniww==",
+                  "coin": "742008225111"
+                },
+                {
+                  "address": "gtgYWEKDWBwQXB0gBCdfHgxlVZOr2iQa4eUdi3cANpMA3QyFoQFYHlgcxdlJsC4jI0tnCIRphMmNR3Oe+l2wxIEj+eCZxgAauVbtDw==",
+                  "coin": "140000000000"
+                }
+              ],
+              "witnesses": {},
+              "collateral": {},
+              "validity": {},
+              "successful": true,
+              "auxiliary": {}
+            }
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+
+## Executing a Streaming Method
+
+Streaming methods are one of the core features of gRPC. To execute a streaming method, such as **FollowTip** in the ChainSyncService:
+
+1. First, understand the method:
+
+```sh
+grpcurl -plaintext localhost:50051 describe utxorpc.sync.v1.ChainSyncService.FollowTip
+```
+
+2. Then execute the method, observing the streaming responses:
+
+```sh
+grpcurl -plaintext localhost:50051 utxorpc.sync.v1.ChainSyncService.FollowTip
+```
+
+## Conclusion
+
+Grpcurl makes interacting with gRPC services as simple as using curl with HTTP APIs. It opens the door for developers to easily test and interact with gRPC services, making the transition from HTTP to gRPC smoother and more approachable.
+
+