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 Required for Celestia gRPC
To ensure secure access to Celestia 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 Celestia gRPC can be handled in two ways:
- Basic Authentication
- 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"
"encoding/base64"
"fmt"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials"
)
func getClientWithBasicAuth(endpoint, token string) (*grpc.ClientConn, error) {
target := endpoint + ".celestia-mainnet.quiknode.pro:9090" // 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 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 9090
. It takes the endpoint name and token as input parameters and returns a gRPC client connection, which you can use to make authenticated API calls.
conn, err := getClientWithBasicAuth("ENDPOINT_NAME", "TOKEN")
if err != nil {
log.Fatalf("err: %v", err)
}
defer conn.Close()
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"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials"
)
func getClientWithXToken(endpoint, token string) (*grpc.ClientConn, error) {
target := endpoint + ".celestia-mainnet.quiknode.pro:9090" // 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 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:
conn, err := getClientWithXToken("ENDPOINT_NAME", "TOKEN")
if err != nil {
log.Fatalf("err: %v", err)
}
defer conn.Close()
The below section provides a step-by-step process to set up a Go environment for making gRPC requests. The instructions include setting up Go, configuring dependencies, and implementing authentication mechanisms.
Initiating the Go Project for Celestia gRPC
Step 1: Create a New Project Directory
Create a dedicated directory for your Celestia gRPC project and navigate into it:
mkdir celestia-grpc
cd celestia-grpc
Step 2: Initialize a Go Module
Create a Go module for your project. The module name can match your directory name or be a repository URL:
go mod init celestia-grpc # directory name
Step 3: Install gRPC and Protobuf Dependencies
Ensure you have both Go and protoc
installed on your machine.
You can Install the core gRPC and Protobuf libraries by following commands:
go get google.golang.org/grpc
go get google.golang.org/protobuf
You can also define versions directly in your go.mod
:
require (
google.golang.org/grpc v1.60.0
google.golang.org/protobuf v1.33.0
)
Next, install the protoc plugins for Go:
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
Make sure $GOPATH/bin
is in your system's PATH. You can follow the steps below to set the system PATH for GO.
To use Go-installed tools globally (e.g., protoc-gen-go
, grpcurl
), add $GOPATH/bin
to your system PATH
.
For macOS / Linux
- Add to your shell config file:
echo 'export PATH="$PATH:$(go env GOPATH)/bin"' >> ~/.bashrc
source ~/.bashrc
Use .zshrc instead of .bashrc if you're using Zsh.
- Verify:
which protoc-gen-go
For Windows
-
Open Start Menu → search for Environment Variables
-
Under System Variables, select Path → click Edit
-
Click New and add:
%USERPROFILE%\go\bin
- Open a new Command Prompt or PowerShell and verify:
where protoc-gen-go
Step 4: Organize Your Project Directory
Download the official Celestia proto files from the celestiaorg/celestia-app repository. You can use the following commands:
# Create celestia folder for proto files
mkdir celestia
# Clone the repository with minimal depth
git clone https://github.com/celestiaorg/celestia-app.git --depth=1
# Copy the proto files to your working directory
cp -r celestia-app/proto/celestia/* celestia/
# Remove the cloned repository (optional)
rm -rf celestia-app
Your project structure should look like this:
celestia-grpc/
├── celestia/
│ ├── blob/
│ │ └── v1/
│ │ ├── params.proto
│ │ ├── query.proto
│ │ └── tx.proto
│ ├── signal/
│ │ └── v1/
│ │ ├── query.proto
│ │ ├── tx.proto
│ │ └── upgrade.proto
│ ├── mint/
│ │ └── v1/
│ │ └── query.proto
│ └── ... (other modules)
├── go.mod
Step 5: Download all the Dependencies
Now, we need to create and run a setup script to automatically download all dependencies. For that first we need to create a setup_celestia_protos.sh
file:
touch setup_celestia_protos.sh
Once created, copy paste the below code to setup_celestia_protos.sh
file:
#!/bin/bash
set -e
echo "Setting up Celestia proto files and dependencies..."
# Create directory structure
mkdir -p celestia/{blob,signal,mint,minfee,qgb}/v1
mkdir -p celestia/core/v1/{gas_estimation,tx}
mkdir -p third_party/{gogoproto,cosmos_proto,google/api}
mkdir -p third_party/cosmos/{base/query/v1beta1,msg/v1}
# Download Celestia proto files
echo "Downloading Celestia proto files..."
git clone https://github.com/celestiaorg/celestia-app.git --depth=1 temp_celestia
cp -r temp_celestia/proto/celestia/* celestia/
rm -rf temp_celestia
# Download dependencies
echo "Downloading dependencies..."
git clone https://github.com/cosmos/gogoproto.git --depth=1 temp_gogoproto
cp temp_gogoproto/gogoproto/gogo.proto third_party/gogoproto/
rm -rf temp_gogoproto
git clone https://github.com/cosmos/cosmos-sdk.git --depth=1 temp_cosmos
cp -r temp_cosmos/proto/cosmos/base/query/v1beta1/* third_party/cosmos/base/query/v1beta1/
cp -r temp_cosmos/proto/cosmos/msg/v1/* third_party/cosmos/msg/v1/
cp -r temp_cosmos/proto/cosmos/* third_party/cosmos_proto/
rm -rf temp_cosmos
# Download cosmos_proto
git clone https://github.com/cosmos/cosmos-proto.git --depth=1 temp_cosmos_proto
cp temp_cosmos_proto/proto/cosmos_proto/cosmos.proto third_party/cosmos_proto/
rm -rf temp_cosmos_proto
git clone https://github.com/googleapis/googleapis.git --depth=1 temp_googleapis
cp temp_googleapis/google/api/annotations.proto third_party/google/api/
cp temp_googleapis/google/api/http.proto third_party/google/api/
rm -rf temp_googleapis
# Download protobuf dependencies
mkdir -p third_party/google/protobuf
curl -s https://raw.githubusercontent.com/protocolbuffers/protobuf/main/src/google/protobuf/descriptor.proto > third_party/google/protobuf/descriptor.proto
curl -s https://raw.githubusercontent.com/protocolbuffers/protobuf/main/src/google/protobuf/timestamp.proto > third_party/google/protobuf/timestamp.proto
curl -s https://raw.githubusercontent.com/protocolbuffers/protobuf/main/src/google/protobuf/field_mask.proto > third_party/google/protobuf/field_mask.proto
echo "Setup complete!"
Once created, now we have to make this script executable and run it by following commands:
chmod +x setup_celestia_protos.sh
sh setup_celestia_protos.sh
After the script completes successfully, your project structure will be as follows:
celestia-grpc/
├── celestia/
│ ├── blob/
│ │ └── v1/
│ │ ├── params.proto
│ │ ├── query.proto
│ │ └── tx.proto
│ ├── signal/
│ │ └── v1/
│ │ ├── query.proto
│ │ ├── tx.proto
│ │ └── upgrade.proto
│ ├── mint/
│ │ └── v1/
│ │ └── query.proto
│ └── ... (other modules)
├── third_party/
│ ├── gogoproto/
│ │ └── gogo.proto
│ ├── cosmos/
│ │ ├── base/
│ │ └── msg/
│ ├── cosmos_proto/
│ │ └── cosmos.proto
│ └── google/
│ └── api/
│ ├── annotations.proto
│ └── http.proto
├── go.mod
Step 5: Generate Go Code from Proto Files
Important: The key to successful proto generation is including the third_party
directory in your proto path. This allows protoc to find all the dependencies like gogoproto/gogo.proto
.
Generate the .pb.go
files by running the following commands with the correct proto paths:
protoc \
--proto_path=. \
--proto_path=./third_party \
--go_out=. \
--go_opt=paths=source_relative \
--go-grpc_out=. \
--go-grpc_opt=paths=source_relative \
celestia/blob/v1/*.proto \
celestia/signal/v1/*.proto \
celestia/mint/v1/*.proto \
celestia/minfee/v1/*.proto \
celestia/core/v1/gas_estimation/*.proto \
celestia/core/v1/tx/*.proto \
celestia/core/v1/proof/*.proto
After the command executes successfully, you will find the generated .pb.go
files inside the celestia
directory, organized by module — such as blob
, core
, mintfee
, and so on.
Step 6: Create a Main Go File
Set up a main Go file for implementing client 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 the Celestia gRPC service to query blob parameters.
package main
import (
"context"
"crypto/tls"
"encoding/json"
"fmt"
"log"
"time"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials"
blobtypes "celestia-grpc/celestia/blob/v1" // Your Generated .pb.go files path
)
// QuickNode endpoints consist of two crucial components: the endpoint name and the corresponding token
// For eg: QN Endpoint: https://docs-demo.celestia-mainnet.quiknode.pro/abcde123456789
// endpoint will be: docs-demo.celestia-mainnet.quiknode.pro:9090 {9090 is the port number for Celestia gRPC}
// token will be : abcde123456789
var token = "YOUR_TOKEN_NUMBER"
var endpoint = "YOUR_QN_ENDPOINT:9090"
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 (a *auth) RequireTransportSecurity() bool {
return false
}
func main() {
creds := credentials.NewTLS(&tls.Config{})
opts := []grpc.DialOption{
grpc.WithTransportCredentials(creds),
grpc.WithPerRPCCredentials(&auth{token}),
}
conn, err := grpc.Dial(endpoint, opts...)
if err != nil {
log.Fatalf("Failed to connect: %v", err)
}
defer conn.Close()
client := blobtypes.NewQueryClient(conn)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
// Query blob parameters
resp, err := client.Params(ctx, &blobtypes.QueryParamsRequest{})
if err != nil {
log.Fatalf("Failed to query blob parameters: %v", err)
}
// Pretty print the response
jsonData, err := json.MarshalIndent(resp, "", " ")
if err != nil {
log.Printf("Error converting to JSON: %v", err)
} else {
fmt.Println("Celestia Blob Parameters:")
fmt.Println(string(jsonData))
}
}
Step 7: 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!