Overview

Python is a versatile and widely-used programming language, known for its simplicity and strong community support. This document provides a step-by-step process for setting up a Python environment to interact with Yellowstone gRPC, including project setup, dependency management, and implementing authentication mechanisms.

Authentication Required for Python

To establish a connection with the Sui gRPC server, first initialize a secure gRPC channel by providing the server's endpoint, including the necessary port (9000), and an authentication token. This setup ensures that the connection is both encrypted and authenticated, allowing the client to communicate securely with the server for executing remote procedure calls (RPCs).

def create_sui_grpc_client(endpoint: str, token: str):
    # 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
    
    # Create secure SSL channel
    channel = grpc.secure_channel(endpoint, grpc.ssl_channel_credentials())
    
    # Create service stub for Ledger operations
    stub = ledger_service_pb2_grpc.LedgerServiceStub(channel)
    
    # Prepare authentication metadata with token
    metadata = [("x-token", token)]
    
    return stub, metadata

You can call the above function like this:

endpoint = 'docs-demo.sui-mainnet.quiknode.pro:9000'
token = 'abcde123456789'
stub, metadata = create_sui_grpc_client(endpoint, token)

Initiating the Python Project for Sui gRPC

Step 1: Create a New Project Directory

Create a dedicated directory for your Sui gRPC project and navigate into it:

mkdir sui-grpc
cd sui-grpc

Step 2: Create Virtual Environment (Recommended)

Create and activate a Python virtual environment to isolate dependencies:

python -m venv venv

# Activate on macOS/Linux
source venv/bin/activate

# Activate on Windows
venv\Scripts\activate

Step 3: Install gRPC and Protobuf Dependencies

Ensure you have Python (3.8+) and protoc installed on your machine. Install the core gRPC and Protocol Buffer libraries:

pip install grpcio grpcio-tools protobuf

Step 4: Organize Your Project Directory

Create a protos folder to store the original Protocol Buffer definition files:

mkdir protos

Download the official Sui proto files from the MystenLabs/sui repository. Extract and place the entire sui directory structure into your newly created protos folder.

Your project structure should look like this:

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

Step 5: Generate Python Code from Proto Files

Once your folder structure matches the above layout, generate the *_pb2_grpc.py and *_pb2.py files by running the following command:

python -m grpc_tools.protoc \
  -I./protos \
  --python_out=. \
  --grpc_python_out=. \
  ./protos/sui/rpc/v2beta/*.proto

It will generate all the required files for running the python examples for Sui gRPC.

Step 6: Create a Client.py File

Set up a main python file for implementing client or server logic:

touch client.py

You can copy and paste the following sample code into your client.py file to get started. The example demonstrates how to interact with the Sui gRPC service to fetch object information.

import grpc
import json
from google.protobuf.field_mask_pb2 import FieldMask
from google.protobuf.json_format import MessageToDict
from sui.rpc.v2beta import ledger_service_pb2, ledger_service_pb2_grpc


def get_object():

    # 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

    endpoint = 'docs-demo.sui-mainnet.quiknode.pro:9000';
    token = 'abcde123456789';

    channel = grpc.secure_channel(endpoint, grpc.ssl_channel_credentials())
    stub = ledger_service_pb2_grpc.LedgerServiceStub(channel)

    # Specify the object ID you want to retrieve
    # Replace with an actual Sui object ID
    object_id = "0x27c4fdb3b846aa3ae4a65ef5127a309aa3c1f466671471a806d8912a18b253e8"

    # Create a field mask to specify which fields to include in the response
    read_mask = FieldMask(paths=[
        "bcs",
        "object_id",
        "version",
        "digest",
        "owner",
        "object_type",
        "has_public_transfer",
        "contents",
        "modules",
        "type_origin_table",
        "linkage_table",
        "previous_transaction",
        "storage_rebate"
    ])

    # Prepare the GetObjectRequest
    request = ledger_service_pb2.GetObjectRequest(
        object_id=object_id,
        read_mask=read_mask
    )

    metadata = [("x-token", token)]

    return stub.GetObject(request, metadata=metadata)


def parse_response_to_json(response):
    return json.dumps(
        MessageToDict(response, preserving_proto_field_name=True),
        indent=2
    )


def main():
    try:
        response = get_object()
        print(parse_response_to_json(response))
    except grpc.RpcError as e:
        print(f"{e.code().name}: {e.details()}")


if __name__ == "__main__":
    main()

Step 7: Run Your Code

Before running your code, clean up and ensure all dependencies are correctly resolved:

python client.py

We ❤️ Feedback!

Feel free to explore the code and use it as a reference for your projects. If you would like us to include Python code examples directly in our documentation, please let us know by filling out this form.