grpc

README

gRPC Execution Client

This package provides a gRPC-based implementation of the Evolve execution interface. It allows Evolve to communicate with remote execution clients via gRPC using the Connect-RPC framework.

Overview

The gRPC execution client enables separation between the consensus layer (Evolve) and the execution layer by providing a network interface for communication. This allows execution clients to run in separate processes or even on different machines.

Usage

Client

To connect to a remote execution service:

import (
    "github.com/evstack/ev-node/execution/grpc"
)

// Create a new gRPC client
client := grpc.NewClient("http://localhost:50051")

// Use the client as an execution.Executor
ctx := context.Background()
stateRoot, maxBytes, err := client.InitChain(ctx, time.Now(), 1, "my-chain")

Server

To serve an execution implementation via gRPC:

import (
    "net/http"
    "github.com/evstack/ev-node/execution/grpc"
)

// Wrap your executor implementation
handler := grpc.NewExecutorServiceHandler(myExecutor)

// Start the HTTP server
http.ListenAndServe(":50051", handler)

Protocol

The gRPC service is defined in proto/evnode/v1/execution.proto and provides the following methods:

• InitChain: Initialize the blockchain with genesis parameters
• GetTxs: Fetch transactions from the mempool
• ExecuteTxs: Execute transactions and update state
• SetFinal: Mark a block as finalized

Features

• Full implementation of the execution.Executor interface
• Support for HTTP/1.1 and HTTP/2 (via h2c)
• gRPC reflection for debugging and service discovery
• Compression for efficient data transfer
• Comprehensive error handling and validation

Testing

Run the tests with:

go test ./execution/grpc/...

The package includes comprehensive unit tests for both client and server implementations.

Documentation

Index

• func NewExecutorServiceHandler(executor execution.Executor, opts ...connect.HandlerOption) http.Handler
• type Client
  • func NewClient(url string, opts ...connect.ClientOption) *Client
  • func (c *Client) ExecuteTxs(ctx context.Context, txs [][]byte, blockHeight uint64, timestamp time.Time, ...) (updatedStateRoot []byte, maxBytes uint64, err error)
  • func (c *Client) GetTxs(ctx context.Context) ([][]byte, error)
  • func (c *Client) InitChain(ctx context.Context, genesisTime time.Time, initialHeight uint64, ...) (stateRoot []byte, maxBytes uint64, err error)
  • func (c *Client) SetFinal(ctx context.Context, blockHeight uint64) error
• type Server
  • func NewServer(executor execution.Executor) *Server
  • func (s *Server) ExecuteTxs(ctx context.Context, req *connect.Request[pb.ExecuteTxsRequest]) (*connect.Response[pb.ExecuteTxsResponse], error)
  • func (s *Server) GetTxs(ctx context.Context, req *connect.Request[pb.GetTxsRequest]) (*connect.Response[pb.GetTxsResponse], error)
  • func (s *Server) InitChain(ctx context.Context, req *connect.Request[pb.InitChainRequest]) (*connect.Response[pb.InitChainResponse], error)
  • func (s *Server) SetFinal(ctx context.Context, req *connect.Request[pb.SetFinalRequest]) (*connect.Response[pb.SetFinalResponse], error)

Functions

func NewExecutorServiceHandler

func NewExecutorServiceHandler(executor execution.Executor, opts ...connect.HandlerOption) http.Handler

NewExecutorServiceHandler creates a new HTTP handler for the ExecutorService. It follows the same pattern as other services in the codebase, supporting both HTTP/1.1 and HTTP/2 without TLS using h2c.

Parameters: - executor: The execution implementation to serve - opts: Optional server options for configuring the service

Returns: - http.Handler: The configured HTTP handler

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a gRPC client that implements the execution.Executor interface. It communicates with a remote execution service via gRPC using Connect-RPC.

func NewClient

func NewClient(url string, opts ...connect.ClientOption) *Client

NewClient creates a new gRPC execution client.

Parameters: - url: The URL of the gRPC server (e.g., "http://localhost:50051") - opts: Optional Connect client options for configuring the connection

Returns: - *Client: The initialized gRPC client

func (*Client) ExecuteTxs

func (c *Client) ExecuteTxs(ctx context.Context, txs [][]byte, blockHeight uint64, timestamp time.Time, prevStateRoot []byte) (updatedStateRoot []byte, maxBytes uint64, err error)

ExecuteTxs processes transactions to produce a new block state.

This method sends transactions to the execution service for processing and returns the updated state root after execution. The execution service ensures deterministic execution and validates the state transition.

func (*Client) GetTxs

func (c *Client) GetTxs(ctx context.Context) ([][]byte, error)

GetTxs fetches available transactions from the execution layer's mempool.

This method retrieves transactions that are ready to be included in a block. The execution service may perform validation and filtering before returning transactions.

func (*Client) InitChain

func (c *Client) InitChain(ctx context.Context, genesisTime time.Time, initialHeight uint64, chainID string) (stateRoot []byte, maxBytes uint64, err error)

InitChain initializes a new blockchain instance with genesis parameters.

This method sends an InitChain request to the remote execution service and returns the initial state root and maximum bytes allowed for transactions.

func (*Client) SetFinal

func (c *Client) SetFinal(ctx context.Context, blockHeight uint64) error

SetFinal marks a block as finalized at the specified height.

This method notifies the execution service that a block has been finalized, allowing it to perform cleanup operations and commit the state permanently.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is a gRPC server that wraps an execution.Executor implementation. It handles the conversion between gRPC types and internal types.

func NewServer

func NewServer(executor execution.Executor) *Server

NewServer creates a new gRPC server that wraps the given executor.

Parameters: - executor: The underlying execution implementation to wrap

Returns: - *Server: The initialized gRPC server

func (*Server) ExecuteTxs

func (s *Server) ExecuteTxs(
	ctx context.Context,
	req *connect.Request[pb.ExecuteTxsRequest],
) (*connect.Response[pb.ExecuteTxsResponse], error)

ExecuteTxs handles the ExecuteTxs RPC request.

It processes transactions to produce a new block state by delegating to the underlying executor implementation.

func (*Server) GetTxs

func (s *Server) GetTxs(
	ctx context.Context,
	req *connect.Request[pb.GetTxsRequest],
) (*connect.Response[pb.GetTxsResponse], error)

GetTxs handles the GetTxs RPC request.

It fetches available transactions from the execution layer's mempool.

func (*Server) InitChain

func (s *Server) InitChain(
	ctx context.Context,
	req *connect.Request[pb.InitChainRequest],
) (*connect.Response[pb.InitChainResponse], error)

InitChain handles the InitChain RPC request.

It initializes the blockchain with the given genesis parameters by delegating to the underlying executor implementation.

func (*Server) SetFinal

func (s *Server) SetFinal(
	ctx context.Context,
	req *connect.Request[pb.SetFinalRequest],
) (*connect.Response[pb.SetFinalResponse], error)

SetFinal handles the SetFinal RPC request.

It marks a block as finalized at the specified height.