Using Grpcurl to Interact with U5C

Introduction to Grpcurl

Grpcurl is a command-line tool for interacting with gRPC services, much like how curl is used for HTTP. While HTTP APIs are widespread and familiar, gRPC is becoming popular, especially for microservices due to its efficiency and performance. However, the binary protocol used by gRPC makes it harder to work with traditional tools like curl. Enter Grpcurl - which solves this by bringing that ease and familiarity of curl to gRPC.

Installing Grpcurl

You can install Grpcurl on various operating systems. Detailed installation instructions and binaries are available on the official GitHub repository (opens in a new tab).

Connecting to a U5C Server

To interact with U5C, you first need to connect to a compliant server. You can choose one of the available servers for U5C.

Example: Connecting to a Local Dolos Node (opens in a new tab)

grpcurl -plaintext localhost:50051 list

This command lists the services available on a local Dolos node running on port 50051.

Example: Connecting to a Local Cardano Node API (opens in a new tab)

grpcurl -plaintext localhost:9090 list

This command lists the services available on a Cardano Node API running on port 9090.

Listing Services and Methods

For the following sections, we’ll assume that a UTxORPC node is running locally at localhost:50051. If your node is hosted elsewhere, simply replace "localhost:50051" with the correct URL and port number.

To list all the services or describe a specific method provided by the U5C endpoint, you can use the following commands:

grpcurl -plaintext localhost:50051 list utxorpc.v1alpha.sync.SyncService

Describing a Method

To get more details about a specific gRPC method, you can describe it using Grpcurl. For instance, if you want to describe the FetchBlock method of the SyncService:

grpcurl -plaintext localhost:50051 describe utxorpc.v1alpha.sync.SyncService.FetchBlock

This will return details about the method:

utxorpc.v1alpha.sync.SyncService.FetchBlock is a method:
rpc FetchBlock ( .utxorpc.v1alpha.sync.FetchBlockRequest ) returns ( .utxorpc.v1alpha.sync.FetchBlockResponse );

You can also describe the request message for this method:

grpcurl -plaintext localhost:50051 describe utxorpc.v1alpha.sync.FetchBlockRequest

The output will look like this:

utxorpc.v1alpha.sync.FetchBlockRequest is a message:
// Request to fetch a block by its reference.
message FetchBlockRequest {
  repeated .utxorpc.v1alpha.sync.BlockRef ref = 1;
  .google.protobuf.FieldMask field_mask = 2;
}

Executing a Request/Reply Method

Once you understand the request structure, you can execute a method like FetchBlock to fetch a specific block. Here's an example using a block's index and hash which are its parameters to make a Block Reference or a ref:

grpcurl -plaintext -d '{"ref": [{"index": 61724995, "hash": "1eVsN7YMlpLBKAFCNjes+zcDa/fiEtQ5d1uP6cdtj/U="}]}' localhost:50051 utxorpc.v1alpha.sync.SyncService.FetchBlock

But do note that this sample depends on which network you're in right now. You may find a block's index and hash from your node's network through other sources in Cardano. But for the current example we're using a preview node.

In this example, the block hash is base64-encoded. The response looks similar to this:

{
  "block": [
    {
      "nativeBytes": "ggeFgooaACcESBoDrdlDWCAnkCF3rtAsCpHfVvTy9+NFiXIBYoAThcbTk1Z0txLPr1ggK1eZ8uNhRbMbKL+jcfyQ/IZfK/U0DwiU8+Pr/BKXSvVYIHGuxo/Z+o4sIzKlrg26zlfPMX9HSmTV8yZNvwv/ZRZYglhAVUw7ggt4IEfPnoUkjJJHv9gy0Cs8PkE9o2fRSaUHyMpGpO0boIkfyx04J3mX3MDAD5mFuwDgVzorvlyyxZsTWVhQnCTkvpXKidNGxCVAbRhXmOy8xswhm+FrfEQ0xCTch+48mWZcNfFVgm51RSd2kUr6m1A4q5dIOTKIZhfX5QMGPXAjzdzATdXu/9636T+mgQEEWCApVx0W8IFwmzxIZRhgB3vr+TQKuz/HEzRDxU8fWl7c8YRYICcRRHXgLsoi3KIu3YK6NSr34OcMvnY60Wv1+VK6vFTQCBkB2lhA0OS7Vb+HWCswkdWtDCm8DyEqPsw7rjXxDgzxTYm8lOF3nvkJTj8BSBJ9fiTx8roFXOIY3h9qj5Ys8MUX0V84CoIJAVkBwBfOLrhPCQ3dzXU3Fhdyjse6uB1emBtGoEcxIQDZnHnSpriV87rasiU+Y63xs5o2ZR/EEcWQNYOl9GDvYv7rmQT2NTrBgIGCemZQgWHPtm7ljJDkd2fVY/XrfKE7z16G2KIV/7+KH2RblJ1ykvpBJBzMAZyAwxkmHGZZe7CN8hvHOHHZJnvFaxSuZBVXgpUuOpESQYXizt2YoqLBWXYqRPrQuOsfCLwWYc7eFSAovAzC9s4zERz9lJXuoQhrLjKdO2kxZuCjpOOhEP2BPCJPbstgWTCAXoLdlDf9l/tMZHEZLFabf3MJ4afJWIDBUuNPTGa2k6iPhwc/uaztTJn3zDC2yLaCs1vhB6xCF74cih8fPPDuS8pCPXHHvVBi03CQpwR6DMvh/0DQqO/3z8l2hkc66PEgGr+h9AyOXBeIBKDpHJeheJ7nVzfK52VBlZQMq4tlLMwsN/+b5y66CXPrJiU/o14wpLqXIf/rnQStspjIX3akaIIAQnl25rzN4O1NGegP/4BHlh4lSno+eu8n/2Z8WhMN3eN+rWbXNiPqISLecSOWTn0cUmN//zGv2xdltXPgj6Lkm84QKfIkYzsehoWAgKCA",
      "cardano": {
        "header": {
          "slot": "61724995",
          "hash": "1eVsN7YMlpLBKAFCNjes+zcDa/fiEtQ5d1uP6cdtj/U=",
          "height": "2557000"
        },
        "body": {}
      }
    }
  ]
}

Executing a Streaming Method

gRPC supports streaming methods, which allow for continuous data exchange between the client and server. To execute a streaming method like FollowTip in the SyncService, follow these steps:

Step 1: Describe the Method

First, understand the method:

grpcurl -plaintext localhost:50051 describe utxorpc.v1alpha.sync.SyncService.FollowTip

Step 2: Execute the Streaming Method

Now, you can execute the method and observe the real-time streaming responses:

grpcurl -plaintext localhost:50051 utxorpc.v1alpha.sync.SyncService.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.

Teams Blaze Provider