Skip to main content

Yellowstone gRPC (Geyser Plugin) Overview

Updated on
Nov 15, 2024

Overview​

Yellowstone gRPC is a high-performance Solana Geyser plugin that enables real-time blockchain data streaming through gRPC interfaces. It serves as a powerful tool for developers who need to:

  • Stream blockchain data in real-time
  • Monitor on-chain activities (token mints, program interactions, state changes)
  • Query account states efficiently
  • Track transactions with minimal latency

The plugin extends Solana's Geyser infrastructure by supporting both gRPC and JSON-RPC protocols, offering offering enterprise-grade reliability with granular control.

Access​

To access Yellowstone gRPC, you need to have the Yellowstone gRPC add-on enabled on your QuickNode endpoint.

Endpoint and Token Configuration​

Yellowstone gRPC operates on port 10000. This is a dedicated secure port for gRPC communication and is separate from the standard Solana RPC endpoint. When connecting to the service the port must be specified in the URL:

  • Endpoint: The name of your gRPC-enabled endpoint (by default, this is three randomly generated words) followed by .solana-mainnet.quiknode.pro and the port number 10000 (e.g., https://example-guide-demo.solana-mainnet.quiknode.pro:10000)
  • Token: The alphanumeric string that follows the endpoint name in the URL (additional tokens can be generated from the QuickNode Dashboard) Endpoint Security tab.

Given the following example HTTP Provider URL: https://example-guide-demo.solana-mainnet.quiknode.pro/123456789/, your authentication your credentials would be:

  • Endpoint: https://example-guide-demo.solana-mainnet.quiknode.pro:10000
  • Token: 123456789

Here is a sample for using this endpoint to connect with TypeScript:

import { Client } from '@rpcpool/yellowstone-grpc';
// For HTTP Provider URL: https://example-guide-demo.solana-mainnet.quiknode.pro/123456789/
const ENDPOINT = 'https://example-guide-demo.solana-mainnet.quiknode.pro:10000';
const TOKEN = '123456789';
const client = new Client(ENDPOINT, TOKEN, {});

Making Yellowstone gRPC Requests​

In Yellowstone gRPC documentation, you will see example requests made with go and typescript programming language for each supported Yellowstone gRPC method. This section will explain how to execute each one of them on your machine.

GO​

Setting up GO​

Go is a statically-typed, compiled language known for its simplicity, efficiency, and strong concurrency support, making it well-suited for developing applications and services. You can follow this official installation document for more information. Check if you have it by running the following:

go version

Authentication Required for GO​

To ensure secure access to Yellowstone gRPC, users are required to authenticate themselves. This authentication process is necessary before utilizing any method. QuickNode endpoints consist of two crucial components: the endpoint name and the corresponding token. Users will need to use these two components to configure a gRPC client with authentication credentials before they make any method calls.

Authentication for the Yellowstone gRPC can be handled in two ways:

  1. Basic Authentication
  2. x-token Authentication

Throughout this documentation, we will call either the getClientWithBasicAuth or getClientWithXToken functions to demonstrate how to handle these different authentication mechanisms.

Basic Authentication​

The getClientWithBasicAuth function demonstrates how to handle authentication using Basic Authentication, which encodes the credentials as base64. Below is the code implementation of the getClientWithBasicAuth function as well as the basicAuth implementation of RPC credentials:

import (
    "context"
    "crypto/tls"
    "fmt"
    "log"
    "time"
    "github.com/mr-tron/base58"
    "encoding/json"

    pb "yellowstone/proto"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/encoding/gzip"
    "google.golang.org/grpc/keepalive"
)

func getClientWithBasicAuth(endpoint, token string) (client.GRPCClient, error) {
    target := endpoint + ".solana-mainnet.quiknode.pro:10000" // for TLS connections
    conn, err := grpc.Dial(target,
        grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})),
        grpc.WithPerRPCCredentials(basicAuth{
            username: endpoint,
            password: token,
        }),
    )
    if err != nil {
        return nil, fmt.Errorf("Unable to dial endpoint %w", err)
    }
    return client.NewGRPCClient(conn), nil
}

// basicAuth implements the credentials.PerRPCCredentials interface to support basic authentication for grpc requests.
type basicAuth struct {
    username string
    password string
}

func (b basicAuth) GetRequestMetadata(ctx context.Context, in ...string) (map[string]string, error) {
    auth := b.username + ":" + b.password
    enc := base64.StdEncoding.EncodeToString([]byte(auth))
    return map[string]string{"authorization": "Basic " + enc}, nil
}

func (basicAuth) RequireTransportSecurity() bool {
    return false
}

The getClientWithBasicAuth function configures a gRPC client with the necessary security options and establishes a connection to the specified endpoint on port 10000. It takes the endpoint name and token as input parameters and returns an instance of the GRPCClient interface, which you can use to make authenticated API calls.

client, err := getClientWithBasicAuth("ENDPOINT_NAME", "TOKEN")
if err != nil {
    log.Fatalf("err: %v", err)
}

x-token Authentication​

The getClientWithXToken function demonstrates how to handle authentication using an x-token. This method attaches the token to the x-token header of each request.


import (
    "context"
    "crypto/tls"
    "fmt"
    "log"
    "time"
    "github.com/mr-tron/base58"
    "encoding/json"

    pb "yellowstone/proto"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/encoding/gzip"
    "google.golang.org/grpc/keepalive"
)

func getClientWithXToken(endpoint, token string) (client.GRPCClient, error) {
    target := endpoint + ".solana-mainnet.quiknode.pro:10000" // for TLS connections
    conn, err := grpc.Dial(target,
        grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})),
        grpc.WithPerRPCCredentials(auth{
            token: token,
        }),
    )
    if err != nil {
        return nil, fmt.Errorf("Unable to dial endpoint %w", err)
    }
    return client.NewGRPCClient(conn), nil
}

// auth implements the credentials.PerRPCCredentials interface to support x-token authentication for grpc requests.
type auth struct {
    token string
}

func (a *auth) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error) {
    return map[string]string{
        "x-token": a.token,
    }, nil
}

func (auth) RequireTransportSecurity() bool {
    return false
}

This method configures a gRPC client similarly to the basic authentication example, but it attaches the authentication token in the x-token header. Here's how you can use this function to make API calls:


client, err := getClientWithXToken("ENDPOINT_NAME", "TOKEN")
if err != nil {
    log.Fatalf("err: %v", err)
}

TypeScript​

Setting up TypeScript​

To run our TypeScript code examples, you'll need to have Node.js installed, as TypeScript is built on top of JavaScript. Ensure you also have TypeScript installed globally by running:

npm install -g typescript

Authentication Required for TypeScript​

Creates a client in order to communicate with a Yellowstone plugin. It uses an endpoint URL and an authentication token for secure access.

const client = new Client(ENDPOINT, TOKEN, {});

Resources​

We ❤️ Feedback!​

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

Last updated on
Share this doc