Overview

grpcurl is a command-line tool that lets you interact with gRPC servers. It's like curl but for gRPC servers. grpcurl is particularly useful for testing and debugging gRPC services without writing any code. This document provides a step-by-step process for setting up grpcurl to interact with Sui gRPC, including installation, configuration, and implementing authentication mechanisms.

Authentication Required for grpcurl

To authenticate with Sui gRPC servers using grpcurl, you need to use x-token authentication. Use the -H flag to add the token as a header:

# QuickNode endpoints consist of two crucial components: the endpoint name and the corresponding token
# For eg: QN Endpoint: https://docs-demo.sui-mainnet.quiknode.pro/abcde123456789
# endpoint will be: docs-demo.sui-mainnet.quiknode.pro:9000  {9000 is the port number for Sui gRPC}
# token will be: abcde123456789

grpcurl -H "x-token: abcde123456789" \
  -proto ./protos/sui/rpc/v2beta/ledger_service.proto \
  docs-demo.sui-mainnet.quiknode.pro:9000 \
  sui.rpc.v2beta.LedgerService/GetObject

Installing grpcurl

macOS

Install using Homebrew:

brew install grpcurl

Linux

Download the latest release from the GitHub releases page:

# Example for Linux AMD64
wget https://github.com/fullstorydev/grpcurl/releases/download/v1.8.9/grpcurl_1.8.9_linux_x86_64.tar.gz
tar -xvf grpcurl_1.8.9_linux_x86_64.tar.gz
sudo mv grpcurl /usr/local/bin/

Windows

Download the Windows binary from the GitHub releases page and add it to your PATH.

Verify Installation

After installation, verify grpcurl is working:

grpcurl --version

Setting up grpcurl for Sui gRPC

Step 1: Create a Working Directory

Create a dedicated directory for your Sui gRPC interactions:

mkdir sui-grpc
cd sui-grpc

Step 2: Download Proto Files

Download the official Sui proto files from the MystenLabs/sui repository:

# Clone the repository with minimal depth
git clone https://github.com/MystenLabs/sui.git --depth=1

# Copy the proto files to your working directory
cp -r sui/crates/sui-rpc-api/proto .

# Remove the cloned repository (optional)
rm -rf sui

Your directory structure should look like this:

sui-grpc/
└── proto/
    └── sui/
        └── rpc/
            └── v2beta/
                ├── ledger_service.proto
                ├── common.proto
                ├── transaction.proto
                ├── checkpoint.proto
                └── ... (other proto files)

Important Note: When using grpcurl with Sui proto files, you'll need to specify multiple proto files because of interdependencies. The ledger service imports types from other proto files like checkpoint.proto, common.proto, etc.

Step 3: Test Your Setup

Start by navigating to the proto directory using the following command:

cd proto

Once inside the folder, you can test your setup by sending a basic request. Keep in mind that depending on the service definition, you may need to include multiple .proto files when invoking the request.

# Example with multiple proto files for dependencies
grpcurl \
  -proto ./sui/rpc/v2beta/ledger_service.proto \
  -proto ./sui/rpc/v2beta/checkpoint.proto \
  -H "x-token: YOUR_TOKEN" \
  -d '{
    "requests": [
      {
        "object_id": "0x27c4fdb3b846aa3ae4a65ef5127a309aa3c1f466671471a806d8912a18b253e8"
      }
    ]
  }' \
  docs-demo.sui-mainnet.quiknode.pro:9000 \
  sui.rpc.v2beta.LedgerService/BatchGetObjects

We ❤️ Feedback!

If you have any feedback or questions about this documentation, let us know. We'd love to hear from you!