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 Yellowstone gRPC server, first initialize a secure gRPC channel by providing the server's endpoint, including the necessary port(1000), 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_grpc_channel(endpoint: str, token: str) -> grpc.Channel:
    # Remove http:// or https:// from the endpoint if present
    endpoint = endpoint.replace('http://', '').replace('https://', '')
    
    # Create authentication credentials
    auth_creds = grpc.metadata_call_credentials(
        lambda context, callback: callback((("x-token", token),), None)
    )

    # Create SSL credentials
    ssl_creds = grpc.ssl_channel_credentials()

    # Combine authentication and SSL credentials
    combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)

    # Create and return the secure channel
    return grpc.secure_channel(endpoint, credentials=combined_creds)

You can call the above function like this:

# Create channel
channel = create_grpc_channel(
    "your-endpoint.example.com:10000",  # Remember to use port 10000
    "your-auth-token"
)

# Create stub for making RPC calls
stub = geyser_pb2_grpc.GeyserStub(channel)

Note:

To learn how to split your Solana Yellowstone enabled URL into endpoint and token, refer to this section - Endpoint and Token Configuration

Environment Setup and gRPC Preparation

Step 1: Create and Activate a Python Virtual Environment

Create a virtual environment to isolate dependencies:

python -m venv venv

Activate the environment by the following commands:

For macOS/Linux:

source venv/bin/activate

For Windows:

venv\Scripts\activate.bat

Step 2: Define Dependencies

Create a requirements.txt file to specify the necessary dependencies for gRPC and related functionalities:

echo "click==8.1.7
grpcio==1.63.0
grpcio-tools==1.63.0
protobuf==5.26.1
base58==2.1.1" > requirements.txt

Install the dependencies:

python -m pip install -r requirements.txt

Step 3: Prepare for gRPC Data Type Generation

Organize your project directory to handle .proto files and their generated stubs:

1. Create a directory for .proto files:

   mkdir proto  # Add your .proto files here

You will need to save geyser.proto and solana-storage.proto in this directory. You can access those files here. These define the Geyser interfaces that we will need to interact with Yellowstone.

2. Create a directory for the generated Python stubs:

   mkdir generated

Step 4: Generate Python Stubs Using grpc_tools.protoc

Run the following command to generate Python files from the .proto definitions:

python -m grpc_tools.protoc \
  -I./proto/ \
  --python_out=./generated \
  --pyi_out=./generated \
  --grpc_python_out=./generated \
  ./proto/*

Verify that the generated files are available in the generated directory. Typical file names include:

• geyser_pb2.py
• geyser_pb2_grpc.py
• solana_storage_pb2.py
• solana_storage_pb2_grpc.py

Step 5: Enable Module Imports

To ensure Python treats the generated directory as a module, create an __init__.py file:

touch generated/__init__.py

You can use our reference file unless you wish to make your own changes.

Sample Python Application for Yellowstone Plugin

A sample Python application demonstrating gRPC interaction with the Yellowstone Geyser Plugin is available in the following GitHub repository: Yellowstone Python Sample App

This example includes:

• Establishing a connection to the Yellowstone service.
• Sending requests and handling responses using gRPC.
• Managing Solana data via the Geyser Plugin.

Additional Notes

• Ensure that your .proto files are correctly defined and added to the proto directory.
• For detailed usage of the generated stubs, refer to the sample application linked above.
• If you encounter any issues, consider updating your dependencies or checking for compatibility with your Python version.

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.