gRPC

Creating a subscription

Streams are available with gRPC via Gateway only. To enable gRPC on your Gateway, use the startup flag grpc.

In order to create a subscription via gRPC, you must first open a gRPC connection to the Gateway using the gRPC host IP and port specified by the startup parameters grpc-host (default: 127.0.0.1) and grpc-port (default: 5001).

The Gateway client connection interface provides a unique method and request for each stream that should be used to create subscriptions. Transaction stream requests have a Filters field, and all stream requests have an Includes field. Stream-specific options for these fields can be found on the dedicated page for that stream. In addition, all stream requests also require the Authorization header configured to authenticate the client. If it is missing or improperly provided, an error will be returned as the response.

Some of gRPC response fields are deprecated and are not populated by the gateway. Check proto file to see response schemas.

Examples

Gateway-API

Subscribing to Gateway Stream in Go using gRPC (ex: NewTxs stream):

package main

import (
	"context"
	"fmt"
	"time"

	pb "github.com/bloXroute-Labs/gateway/v2/protobuf"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
)

type blxrCredentials struct {
	authorization string
}

func (bc blxrCredentials) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error) {
	return map[string]string{
		"authorization": bc.authorization,
	}, nil
}

func (bc blxrCredentials) RequireTransportSecurity() bool {
	return false
}

func main() {
	// gRPC server default values
	gatewayHostIP := "localhost"
	gatewayGRPCPort := 5001
	
	// this will use localhost CA to verify the certificate
	creds := credentials.NewClientTLSFromCert(nil, "")

	// Open gRPC connection to Gateway.
	conn, _ := grpc.Dial(
		fmt.Sprintf("%v:%v", gatewayHostIP, gatewayGRPCPort),
		grpc.WithTransportCredentials(creds),
		grpc.WithPerRPCCredentials(blxrCredentials{authorization: "<YOUR-AUTHORIZATION-HEADER>"}),
		// for the best networking performance between gateway and a client
		// we recommend to use following dial configuration:
		grpc.WithWriteBufferSize(0),
		grpc.WithInitialConnWindowSize(128*1024),
	)

	// Use the Gateway client connection interface.
	client := pb.NewGatewayClient(conn)

	// create context and defer cancel of context
	callContext, cancel := context.WithTimeout(context.Background(), 24*time.Hour)
	defer cancel()

	// Create a subscription using the stream-specific method and request.
	stream, _ := client.NewTxs(callContext, &pb.TxsRequest{Filters: "", Includes: ""})

	for {
		subscriptionNotification, err := stream.Recv()
		if err == nil {
			fmt.Println(subscriptionNotification) // or process it generally
		}
	}
}