consensus/bor, internal/cli: full grpc implementation

cmd/keeper/go.mod

@@ -50,7 +50,7 @@ require (
 	github.com/yusufpapurcu/wmi v1.2.4 // indirect
 	golang.org/x/crypto v0.46.0 // indirect
 	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/sys v0.40.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
 	golang.org/x/time v0.12.0 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 )

cmd/keeper/go.sum

@@ -165,8 +165,8 @@ golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
-golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/text v0.32.0 h1:ZD01bjUt1FQ9WJ0ClOL5vxgxOI/sVCNgX1YtKwcY0mU=
 golang.org/x/text v0.32.0/go.mod h1:o/rUWzghvpD5TXrTIBuJU77MTaN0ljMWE47kxGJQ7jY=
 golang.org/x/time v0.12.0 h1:ScB/8o8olJvc+CQPWrK3fPZNfh7qgwCrY0zJmoEQLSE=

consensus/bor/api.go

@@ -277,7 +277,9 @@ func (api *API) GetCurrentValidators() ([]*valset.Validator, error) {
 	return snap.ValidatorSet.Validators, nil
 }
 
-// GetRootHash returns the merkle root of the start-to-end blocks' headers
+// GetRootHash returns the merkle root of the start-to-end blocks' headers.
+// rootHashCache is normally initialized eagerly inside Bor.APIs (sync.Once);
+// the lazy init below is kept as fallback for direct-API paths (e.g., tests) that don't go through Bor.APIs.
 func (api *API) GetRootHash(start uint64, end uint64) (string, error) {
 	if err := api.initializeRootHashCache(); err != nil {
 		return "", err

consensus/bor/bor.go

@@ -278,6 +278,10 @@ type Bor struct {
 	// ctx is cancelled when Close() is called, allowing in-flight operations to abort promptly.
 	ctx       context.Context
 	ctxCancel context.CancelFunc
+
+	// api is the bor engine API instance reused across all callers (JSON-RPC and gRPC).
+	api     *API
+	apiOnce sync.Once
 }
 
 type signer struct {
@@ -1529,11 +1533,29 @@ func (c *Bor) SealHash(header *types.Header) common.Hash {
 
 // APIs implements consensus.Engine, returning the user facing RPC API to allow
 // controlling the signer voting.
+//
+// The returned *API is cached on the first call so that per-API state (e.g.,
+// rootHashCache) persists across calls. JSON-RPC only invokes APIs() once at
+// node startup, but the gRPC backend fetches it on every handler call — without
+// the cache those calls would each start from an empty state.
+//
+// rootHashCache is initialized here (inside the sync.Once) rather than lazily
+// in GetRootHash so that concurrent gRPC handlers sharing the cached *API
+// cannot race in initializeRootHashCache.
 func (c *Bor) APIs(chain consensus.ChainHeaderReader) []rpc.API {
+	c.apiOnce.Do(func() {
+		a := &API{chain: chain, bor: c}
+		if err := a.initializeRootHashCache(); err != nil {
+			// log.Crit logs at the highest severity and then exits the process;
+			// This is currently unreachable (size is a constant in initializeRootHashCache),
+			log.Crit("bor: failed to initialize rootHashCache", "err", err)
+		}
+		c.api = a
+	})
 	return []rpc.API{{
 		Namespace: "bor",
 		Version:   "1.0",
-		Service:   &API{chain: chain, bor: c},
+		Service:   c.api,
 		Public:    false,
 	}}
 }

consensus/bor/bor_test.go

@@ -2040,6 +2040,20 @@ func TestAPIs_ReturnsBorNamespace(t *testing.T) {
 	require.Equal(t, "1.0", apis[0].Version)
 }
 
+// TestAPIs_ReturnsSameInstanceAcrossCalls verifies that repeated calls to APIs() must return the same *API
+// so per-API state such as rootHashCache persists across calls. This matters for the gRPC backend
+// which fetches APIs() on every handler invocation; returning a fresh *API each call defeats caching.
+func TestAPIs_ReturnsSameInstanceAcrossCalls(t *testing.T) {
+	t.Parallel()
+	sp := &fakeSpanner{vals: []*valset.Validator{{Address: common.HexToAddress("0x1"), VotingPower: 1}}}
+	borCfg := defaultBorConfig()
+	chain, b := newChainAndBorForTest(t, sp, borCfg, false, common.Address{}, uint64(time.Now().Unix()))
+
+	first := b.APIs(chain.HeaderChain())
+	second := b.APIs(chain.HeaderChain())
+	require.Same(t, first[0].Service, second[0].Service, "APIs must return the cached *API on repeated calls")
+}
+
 func TestClose_Idempotent(t *testing.T) {
 	t.Parallel()
 	sp := &fakeSpanner{vals: []*valset.Validator{{Address: common.HexToAddress("0x1"), VotingPower: 1}}}

docs/cli/default_config.toml

@@ -220,6 +220,7 @@ devfakeauthor = false
 
 [grpc]
   addr = "127.0.0.1:3131"
+  token = ""
 
 [developer]
   dev = false

docs/cli/server.md

@@ -64,7 +64,9 @@ The ```bor server``` command runs the Bor client.
 
 - ```gpo.percentile```: Suggested gas price is the given percentile of a set of recent transaction gas prices (default: 60)
 
-- ```grpc.addr```: Address and port to bind the GRPC server (default: 127.0.0.1:3131)
+- ```grpc.addr```: Address and port to bind the GRPC server. Empty disables the server. Non-loopback binds without --grpc.token log a startup warning. (default: 127.0.0.1:3131)
+
+- ```grpc.token```: Raw token expected in the `authorization: Bearer <token>` header of incoming gRPC calls (empty disables auth; the `Bearer ` prefix is stripped before comparison). Prefer the BOR_GRPC_TOKEN environment variable over this flag.
 
 - ```history.logs```: Number of recent blocks to maintain log search index for (default = about 2 months, 0 = entire chain) (default: 2350000)
 

go.mod

@@ -6,7 +6,7 @@ go 1.26.2
 require (
 	github.com/0xPolygon/crand v1.0.3
 	github.com/0xPolygon/heimdall-v2 v0.6.0
-	github.com/0xPolygon/polyproto v0.0.7
+	github.com/0xPolygon/polyproto v0.0.8-0.20260423132317-7d955b45ef8a
 	github.com/Azure/azure-sdk-for-go/sdk/storage/azblob v1.3.2
 	github.com/BurntSushi/toml v1.4.0
 	github.com/JekaMas/go-grpc-net-conn v0.0.0-20220708155319-6aff21f2d13d

go.sum

@@ -88,8 +88,8 @@ github.com/0xPolygon/crand v1.0.3 h1:BYYflmgLhmGPEgqtopG4muq6wV6DOkwD8uPymNz5WeQ
 github.com/0xPolygon/crand v1.0.3/go.mod h1:km4366oC7EVFl1xNUCwzxUXNM10swZqd8LZ0E5SgbAE=
 github.com/0xPolygon/heimdall-v2 v0.6.0 h1:rA8RISMnns1w08PxTLvDBS5WiaTOFHJGSrhDWDJLtHc=
 github.com/0xPolygon/heimdall-v2 v0.6.0/go.mod h1:fVkGiODG6cGLaDyrE3qxIrvz1rbUr4Zdrr3dOm2SPgg=
-github.com/0xPolygon/polyproto v0.0.7 h1:Ody+kFyCRK4QXRPXbsP5pdxKrDgwAAXtFB8NPgaIxRs=
-github.com/0xPolygon/polyproto v0.0.7/go.mod h1:2Iw93k2LismvckKKeXQITuhJH9vLbqOa212AMskH6no=
+github.com/0xPolygon/polyproto v0.0.8-0.20260423132317-7d955b45ef8a h1:vVtSjO29FcFBZbNVsVGy6z3lv3RRr/sI1vPR7IzbZZE=
+github.com/0xPolygon/polyproto v0.0.8-0.20260423132317-7d955b45ef8a/go.mod h1:2Iw93k2LismvckKKeXQITuhJH9vLbqOa212AMskH6no=
 github.com/99designs/go-keychain v0.0.0-20191008050251-8e49817e8af4 h1:/vQbFIOMbk2FiG/kXiLl8BRyzTWDw7gX/Hz7Dd5eDMs=
 github.com/99designs/go-keychain v0.0.0-20191008050251-8e49817e8af4/go.mod h1:hN7oaIRCjzsZ2dE+yG5k+rsdt3qcwykqK6HVGcKwsw4=
 github.com/99designs/keyring v1.2.2 h1:pZd3neh/EmUzWONb35LxQfvuY7kiSXAq3HQd97+XBn0=

internal/cli/command.go

@@ -1,6 +1,7 @@
 package cli
 
 import (
+	"context"
 	"fmt"
 	"os"
 
@@ -222,7 +223,8 @@ func Commands() map[string]MarkDownCommandFactory {
 type Meta2 struct {
 	UI cli.Ui
 
-	addr string
+	addr  string
+	token string
 }
 
 func (m *Meta2) NewFlagSet(n string) *flagset.Flagset {
@@ -234,12 +236,55 @@ func (m *Meta2) NewFlagSet(n string) *flagset.Flagset {
 		Usage:   "Address of the grpc endpoint",
 		Default: "127.0.0.1:3131",
 	})
+	f.StringFlag(&flagset.StringFlag{
+		Name:    "token",
+		Value:   &m.token,
+		Usage:   "Bearer token to authenticate with the bor gRPC server (matches --grpc.token on the server). Falls back to the BOR_GRPC_TOKEN environment variable when unset.",
+		Default: "",
+	})
 
 	return f
 }
 
+// bearerCreds implements grpc/credentials.PerRPCCredentials for the
+// "Authorization: Bearer <token>" header the bor gRPC server expects.
+// Local-only: not exported.
+type bearerCreds struct{ token string }
+
+func (b bearerCreds) GetRequestMetadata(_ context.Context, _ ...string) (map[string]string, error) {
+	return map[string]string{"authorization": "Bearer " + b.token}, nil
+}
+
+// RequireTransportSecurity returns false so the credentials still attach
+// when the CLI dials a plaintext loopback server (the common case for
+// `bor status` etc. against same-host bor). Cross-host TLS plumbing for
+// the CLI is a separate concern not addressed here.
+func (b bearerCreds) RequireTransportSecurity() bool { return false }
+
 func (m *Meta2) Conn() (*grpc.ClientConn, error) {
-	conn, err := grpc.NewClient(m.addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	// Token resolution: --token flag > BOR_GRPC_TOKEN env var > unauthenticated.
+	// Mirrors the server-side precedence so an operator who exports
+	// BOR_GRPC_TOKEN once gets both `bor server` AND `bor <subcmd>` to use it.
+	token := m.token
+	if token == "" {
+		token = os.Getenv("BOR_GRPC_TOKEN")
+	}
+
+	opts := []grpc.DialOption{grpc.WithTransportCredentials(insecure.NewCredentials())}
+	if token != "" {
+		// Symmetric with heimdall's client-side guarantee: refuse to send the
+		// bearer token in cleartext to a non-loopback peer.
+		if !server.IsLoopbackHostPort(m.addr) {
+			return nil, fmt.Errorf(
+				"refusing to send bearer token to non-loopback address %q over plaintext; "+
+					"use --address with a loopback host (e.g. 127.0.0.1:3131) or extend the CLI with TLS support",
+				m.addr,
+			)
+		}
+		opts = append(opts, grpc.WithPerRPCCredentials(bearerCreds{token: token}))
+	}
+
+	conn, err := grpc.NewClient(m.addr, opts...)
 	if err != nil {
 		return nil, fmt.Errorf("failed to connect to server: %v", err)
 	}

internal/cli/command_test.go

@@ -0,0 +1,57 @@
+package cli
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestMeta2Conn_NoToken: default behaviour (no token) keeps the original
+// insecure-only dial. No regressions for the loopback no-auth flow.
+func TestMeta2Conn_NoToken(t *testing.T) {
+	t.Setenv("BOR_GRPC_TOKEN", "")
+	m := &Meta2{addr: "127.0.0.1:3131"}
+	conn, err := m.Conn()
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = conn.Close() })
+}
+
+// TestMeta2Conn_LoopbackWithToken: token attached over plaintext is allowed
+// when the dial address is loopback (the typical same-host validator pair).
+func TestMeta2Conn_LoopbackWithToken(t *testing.T) {
+	t.Setenv("BOR_GRPC_TOKEN", "")
+	m := &Meta2{addr: "127.0.0.1:3131", token: "secret"}
+	conn, err := m.Conn()
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = conn.Close() })
+}
+
+// TestMeta2Conn_NonLoopbackWithTokenRefused: refuse to send a bearer token in
+// cleartext to a remote host. Mirrors the heimdall-side guarantee.
+func TestMeta2Conn_NonLoopbackWithTokenRefused(t *testing.T) {
+	t.Setenv("BOR_GRPC_TOKEN", "")
+	m := &Meta2{addr: "bor.example.net:3131", token: "secret"}
+	_, err := m.Conn()
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "refusing to send bearer token to non-loopback")
+}
+
+// TestMeta2Conn_EnvVarFallback: BOR_GRPC_TOKEN env var is used when --token is
+// not passed. The non-loopback refusal applies to env-supplied tokens too.
+func TestMeta2Conn_EnvVarFallback(t *testing.T) {
+	t.Setenv("BOR_GRPC_TOKEN", "from-env")
+	m := &Meta2{addr: "bor.example.net:3131"}
+	_, err := m.Conn()
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "refusing to send bearer token to non-loopback")
+}
+
+// TestBearerCreds_GetRequestMetadata returns the correctly framed Authorization
+// header with a Bearer scheme.
+func TestBearerCreds_GetRequestMetadata(t *testing.T) {
+	t.Parallel()
+
+	md, err := bearerCreds{token: "abc123"}.GetRequestMetadata(nil)
+	require.NoError(t, err)
+	require.Equal(t, "Bearer abc123", md["authorization"])
+}