Overview

Go is a statically-typed, compiled language known for its simplicity, efficiency, and strong concurrency support. Follow the official installation guide to install Go. Verify the installation:

go version

Authentication for Go Requests

To securely access Yellowstone gRPC, authentication is required. QuickNode endpoints consist of two components: endpoint name and token. You must use these components to configure a gRPC client with authentication credentials.

There are two authentication methods:

1. Basic Authentication
2. x-token Authentication

This document provides implementation details for both methods.

---

Basic Authentication

The getClientWithBasicAuth function demonstrates how to handle authentication using Basic Authentication. It encodes the credentials in base64 and adds them to the authorization header.

Implementation

import (
    "context"
    "crypto/tls"
    "encoding/base64"
    "fmt"
    "log"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
)

func getClientWithBasicAuth(endpoint, token string) (*grpc.ClientConn, error) {
    target := endpoint + ".solana-mainnet.quiknode.pro:10000"
    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 conn, nil
}

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
    encoded := base64.StdEncoding.EncodeToString([]byte(auth))
    return map[string]string{"authorization": "Basic " + encoded}, nil
}

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

Usage

conn, err := getClientWithBasicAuth("ENDPOINT_NAME", "TOKEN")
if err != nil {
    log.Fatalf("failed to connect: %v", err)
}
defer conn.Close()

---

x-token Authentication

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

Implementation

import (
    "context"
    "crypto/tls"
    "fmt"
    "log"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
)

func getClientWithXToken(endpoint, token string) (*grpc.ClientConn, error) {
    target := endpoint + ".solana-mainnet.quiknode.pro:10000"
    conn, err := grpc.Dial(target,
        grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})),
        grpc.WithPerRPCCredentials(xTokenAuth{
            token: token,
        }),
    )
    if err != nil {
        return nil, fmt.Errorf("unable to dial endpoint: %w", err)
    }
    return conn, nil
}

type xTokenAuth struct {
    token string
}

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

func (xTokenAuth) RequireTransportSecurity() bool {
    return true
}

Usage

conn, err := getClientWithXToken("ENDPOINT_NAME", "TOKEN")
if err != nil {
    log.Fatalf("failed to connect: %v", err)
}
defer conn.Close()

---

Note:

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

The below section provides a step-by-step process to set up a Go environment for making gRPC requests to the Yellowstone Geyser Plugin. The instructions include setting up Go, configuring dependencies, and implementing authentication mechanisms.

Initiating the Go Project for Yellowstone gRPC

Step 1: Create a New Project Directory

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

mkdir yellowstone-grpc
cd yellowstone-grpc

Step 2: Initialize a Go Module

Initialize a new Go module for your project:

go mod init yellowstone-grpc # directory name

Step 3: Install Required Dependencies

Install the necessary Go dependencies for gRPC and Protocol Buffers:

go get google.golang.org/grpc
go get google.golang.org/protobuf

Step 4: Organize Your Project Directory

First, create a proto folder to store the .pb.go files:

mkdir proto

You can get the pre-generated files from Yellowstone gRPC official Github Repo. Download all the three files and place the following files into the proto directory:

• geyser_pb.go
• geyser_grpc.pb.go
• solana_storage_pb.go

The project structure might look like this:

yellowstone-grpc/
├── go.mod
├── go.sum
├── proto/
│   ├── geyser_pb.go
│   ├── geyser_grpc.pb.go
│   ├── solana_storage_pb.go

Step 5: Create a Main Go File

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

touch main.go

You can copy and paste the following sample code into your main.go file to get started. The example demonstrates how to interact with a gRPC service to fetch the latest blockhash information.

package main

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

    pb "yellowstone-grpc/proto" # proto directory path

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

var (
    endpoint = "example-guide-demo.solana-mainnet.quiknode.pro:10000"
    token    = "123456789abcdefghijklmnopquerst"
)

var kacp = keepalive.ClientParameters{
    Time:                10 * time.Second,
    Timeout:             time.Second,
    PermitWithoutStream: true,
}

// tokenAuth implements the credentials.PerRPCCredentials interface
type tokenAuth struct {
    token string
}

func (t tokenAuth) GetRequestMetadata(ctx context.Context, in ...string) (map[string]string, error) {
    return map[string]string{"x-token": t.token}, nil
}

func (tokenAuth) RequireTransportSecurity() bool {
    return true
}

func main() {
    opts := []grpc.DialOption{
        grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})),
        grpc.WithKeepaliveParams(kacp),
        grpc.WithDefaultCallOptions(grpc.MaxCallRecvMsgSize(1024*1024*1024), grpc.UseCompressor(gzip.Name)),
        grpc.WithPerRPCCredentials(tokenAuth{token: token}),
    }

    conn, err := grpc.Dial(endpoint, opts...)
    if err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }
    defer conn.Close()

    client := pb.NewGeyserClient(conn)

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    latestBlockHash, err := client.GetLatestBlockhash(ctx, &pb.GetLatestBlockhashRequest{})
    if err != nil {
        log.Fatalf("Failed to get latest blockhash: %v", err)
    }

    fmt.Printf("Latest Blockhash Information:
")
    fmt.Printf("  Blockhash: %+v
", latestBlockHash)
}

Step 6: Run Your Code

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

go mod tidy

Build and run the project using:

go run main.go

We ❤️ Feedback!

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