feat: support for multi gRPC query clients serve with old binary

Author: mmsqe

CHANGELOG.md

@@ -44,6 +44,7 @@ This patch update also includes minor dependency bumps.
 
 * (abci_utils) [#25008](https://github.com/cosmos/cosmos-sdk/pull/24861) add the ability to assign a custom signer extraction adapter in `DefaultProposalHandler`.
 * (x/tx) [#25539](https://github.com/cosmos/cosmos-sdk/pull/25539) Expose `NullSliceAsEmptyEncoder` as a public function and add `null_slice_as_empty` encoding option for protobuf annotations.
+* (gRPC) [#25565](https://github.com/cosmos/cosmos-sdk/pull/25565) Support for multi gRPC query clients serve with old binary.
 
 ## [v0.53.3](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.53.3) - 2025-07-08
 

client/context.go

@@ -30,6 +30,7 @@ type Context struct {
 	FromAddress           sdk.AccAddress
 	Client                CometRPC
 	GRPCClient            *grpc.ClientConn
+	GRPCConnProvider      *GRPCConnProvider
 	ChainID               string
 	Codec                 codec.Codec
 	InterfaceRegistry     codectypes.InterfaceRegistry
@@ -155,6 +156,22 @@ func (ctx Context) WithGRPCClient(grpcClient *grpc.ClientConn) Context {
 	return ctx
 }
 
+// WithGRPCConnProvider returns a copy of the context with an updated GRPCConnProvider.
+func (ctx Context) WithGRPCConnProvider(provider *GRPCConnProvider) Context {
+	ctx.GRPCConnProvider = provider
+	return ctx
+}
+
+// GetGRPCConn returns the appropriate gRPC connection for the given height.
+// If GRPCConnProvider is set, it uses it to determine the connection.
+// Otherwise, it falls back to the default GRPCClient.
+func (ctx Context) GetGRPCConn(height int64) *grpc.ClientConn {
+	if ctx.GRPCConnProvider != nil {
+		return ctx.GRPCConnProvider.GetGRPCConn(height)
+	}
+	return ctx.GRPCClient
+}
+
 // WithUseLedger returns a copy of the context with an updated UseLedger flag.
 func (ctx Context) WithUseLedger(useLedger bool) Context {
 	ctx.UseLedger = useLedger

client/grpc_query.go

@@ -16,11 +16,56 @@ import (
 
 	"github.com/cosmos/cosmos-sdk/codec"
 	"github.com/cosmos/cosmos-sdk/codec/types"
+	"github.com/cosmos/cosmos-sdk/server/config"
 	sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
 	grpctypes "github.com/cosmos/cosmos-sdk/types/grpc"
 	"github.com/cosmos/cosmos-sdk/types/tx"
 )
 
+// GRPCConn provides a method to get the appropriate gRPC connection based on block height.
+type GRPCConn interface {
+	GetGRPCConn(height int64) *grpc.ClientConn
+}
+
+// GRPCConnProvider manages gRPC connections with optional backup connections for historical queries.
+type GRPCConnProvider struct {
+	// DefaultConn is the primary gRPC connection
+	DefaultConn *grpc.ClientConn
+	// BackupConns maps block ranges to backup gRPC connections for routing historical queries
+	BackupConns config.BackupGRPCConnections
+}
+
+// NewGRPCConnProvider creates a new GRPCConnProvider with the given connections.
+func NewGRPCConnProvider(defaultConn *grpc.ClientConn, backupConns config.BackupGRPCConnections) *GRPCConnProvider {
+	if backupConns == nil {
+		backupConns = make(config.BackupGRPCConnections)
+	}
+	return &GRPCConnProvider{
+		DefaultConn: defaultConn,
+		BackupConns: backupConns,
+	}
+}
+
+// GetGRPCConn returns the appropriate gRPC connection based on the block height.
+// For height <= 0 (latest block), it returns the default connection.
+// For positive heights, it checks if a backup connection exists for that height range.
+func (g *GRPCConnProvider) GetGRPCConn(height int64) *grpc.ClientConn {
+	// height = 0 means latest block, use the default connection
+	if height <= 0 {
+		return g.DefaultConn
+	}
+
+	// Check if there's a backup connection for this height
+	for blockRange, conn := range g.BackupConns {
+		if int64(blockRange[0]) <= height && int64(blockRange[1]) >= height {
+			return conn
+		}
+	}
+
+	// Default to the primary connection if no backup matches
+	return g.DefaultConn
+}
+
 var _ gogogrpc.ClientConn = Context{}
 
 // fallBackCodec is used by Context in case Codec is not set.
@@ -58,7 +103,11 @@ func (ctx Context) Invoke(grpcCtx gocontext.Context, method string, req, reply a
 
 	if ctx.GRPCClient != nil {
 		// Case 2-1. Invoke grpc.
-		return ctx.GRPCClient.Invoke(grpcCtx, method, req, reply, opts...)
+		grpcConn := ctx.GRPCClient
+		if ctx.GRPCConnProvider != nil {
+			grpcConn = ctx.GRPCConnProvider.GetGRPCConn(ctx.Height)
+		}
+		return grpcConn.Invoke(grpcCtx, method, req, reply, opts...)
 	}
 
 	// Case 2-2. Querying state via abci query.

server/config/config.go

@@ -1,10 +1,12 @@
 package config
 
 import (
+	"encoding/json"
 	"fmt"
 	"math"
 
 	"github.com/spf13/viper"
+	"google.golang.org/grpc"
 
 	pruningtypes "cosmossdk.io/store/pruning/types"
 
@@ -124,6 +126,12 @@ type APIConfig struct {
 	// Ref: https://github.com/cosmos/cosmos-sdk/issues/6420
 }
 
+type BlockRange [2]int
+
+// BackupGRPCConnections is a map of block ranges to gRPC client connections
+// used for routing requests to different backend nodes based on block height.
+type BackupGRPCConnections map[BlockRange]*grpc.ClientConn
+
 // GRPCConfig defines configuration for the gRPC server.
 type GRPCConfig struct {
 	// Enable defines if the gRPC server should be enabled.
@@ -142,6 +150,9 @@ type GRPCConfig struct {
 
 	// SkipCheckHeader defines if the gRPC server should bypass header checking.
 	SkipCheckHeader bool `mapstructure:"skip-check-header"`
+
+	// BackupGRPCBlockAddressBlockRange maps block ranges to gRPC addresses for routing historical queries.
+	BackupGRPCBlockAddressBlockRange map[BlockRange]string `mapstructure:"-"`
 }
 
 // GRPCWebConfig defines configuration for the gRPC-web server.
@@ -278,6 +289,26 @@ func GetConfig(v *viper.Viper) (Config, error) {
 	if err := v.Unmarshal(conf); err != nil {
 		return Config{}, fmt.Errorf("error extracting app config: %w", err)
 	}
+	raw := v.GetString("grpc.backup-grpc-address-block-range")
+	if len(raw) > 0 {
+		data := make(map[string]BlockRange)
+		if err := json.Unmarshal([]byte(raw), &data); err != nil {
+			return Config{}, fmt.Errorf("failed to parse backup-grpc-address-block-range as JSON: %w (value: %s)", err, raw)
+		}
+		backupGRPCBlockAddressBlockRange := make(map[BlockRange]string, len(data))
+		for address, blockRange := range data {
+			if blockRange[0] < 0 || blockRange[1] < 0 {
+				return Config{}, fmt.Errorf("invalid block range [%d, %d] for address %s: block numbers cannot be negative",
+					blockRange[0], blockRange[1], address)
+			}
+			if blockRange[0] > blockRange[1] {
+				return Config{}, fmt.Errorf("invalid block range [%d, %d] for address %s: start block must be <= end block",
+					blockRange[0], blockRange[1], address)
+			}
+			backupGRPCBlockAddressBlockRange[blockRange] = address
+		}
+		conf.GRPC.BackupGRPCBlockAddressBlockRange = backupGRPCBlockAddressBlockRange
+	}
 	return *conf, nil
 }
 

server/config/toml.go

@@ -182,6 +182,13 @@ max-recv-msg-size = "{{ .GRPC.MaxRecvMsgSize }}"
 # The default value is math.MaxInt32.
 max-send-msg-size = "{{ .GRPC.MaxSendMsgSize }}"
 
+# Backup gRPC addresses with block ranges for historical query routing.
+# This should be a JSON string mapping gRPC addresses to block ranges.
+# Format: '{"address1": [start_block, end_block], "address2": [start_block, end_block]}'
+# Example: '{"0.0.0.0:26113": [0, 1000], "0.0.0.0:26114": [1001, 2000]}'
+# Leave empty to disable backup gRPC routing.
+backup-grpc-address-block-range = "{{ printf "{" }}{{ range $k, $v := .GRPC.BackupGRPCBlockAddressBlockRange }}\"{{ $v }}\": [{{index $k 0 }}, {{ index $k 1}}]{{ end }}{{ printf "}" }}"
+
 ###############################################################################
 ###                        gRPC Web Configuration                           ###
 ###############################################################################

server/start.go

@@ -35,6 +35,8 @@ import (
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/credentials/insecure"
 
+	errorsmod "cosmossdk.io/errors"
+	"cosmossdk.io/log"
 	pruningtypes "cosmossdk.io/store/pruning/types"
 
 	"github.com/cosmos/cosmos-sdk/client"
@@ -96,11 +98,12 @@ const (
 
 	// gRPC-related flags
 
-	flagGRPCOnly            = "grpc-only"
-	flagGRPCEnable          = "grpc.enable"
-	flagGRPCAddress         = "grpc.address"
-	flagGRPCWebEnable       = "grpc-web.enable"
-	flagGRPCSkipCheckHeader = "grpc.skip-check-header"
+	flagGRPCOnly                         = "grpc-only"
+	flagGRPCEnable                       = "grpc.enable"
+	flagGRPCAddress                      = "grpc.address"
+	flagGRPCWebEnable                    = "grpc-web.enable"
+	flagGRPCSkipCheckHeader              = "grpc.skip-check-header"
+	flagBackupGRPCBlockAddressBlockRange = "grpc.backup-grpc-address-block-range"
 
 	// mempool flags
 
@@ -451,6 +454,53 @@ func setupTraceWriter(svrCtx *Context) (traceWriter io.WriteCloser, cleanup func
 	return traceWriter, cleanup, nil
 }
 
+func parseGrpcAddress(address string) (string, error) {
+	host, port, err := net.SplitHostPort(address)
+	if err != nil {
+		return "", errorsmod.Wrapf(err, "invalid grpc address %s", address)
+	}
+	return fmt.Sprintf("%s:%s", host, port), nil
+}
+
+// SetupBackupGRPCConnections creates backup gRPC connections based on the configuration
+// and returns a client context with the GRPCConnProvider configured.
+func SetupBackupGRPCConnections(
+	clientCtx client.Context,
+	grpcClient *grpc.ClientConn,
+	backupAddresses map[serverconfig.BlockRange]string,
+	maxRecvMsgSize, maxSendMsgSize int,
+	logger log.Logger,
+) (client.Context, error) {
+	if len(backupAddresses) == 0 {
+		return clientCtx, nil
+	}
+
+	backupConns := make(serverconfig.BackupGRPCConnections)
+	for blockRange, address := range backupAddresses {
+		grpcAddr, err := parseGrpcAddress(address)
+		if err != nil {
+			return clientCtx, err
+		}
+		conn, err := grpc.NewClient(
+			grpcAddr,
+			grpc.WithTransportCredentials(insecure.NewCredentials()),
+			grpc.WithDefaultCallOptions(
+				grpc.ForceCodec(codec.NewProtoCodec(clientCtx.InterfaceRegistry).GRPCCodec()),
+				grpc.MaxCallRecvMsgSize(maxRecvMsgSize),
+				grpc.MaxCallSendMsgSize(maxSendMsgSize),
+			),
+		)
+		if err != nil {
+			return clientCtx, err
+		}
+		backupConns[blockRange] = conn
+	}
+
+	clientCtx = clientCtx.WithGRPCConnProvider(client.NewGRPCConnProvider(grpcClient, backupConns))
+	logger.Info("backup gRPC connections configured", "count", len(backupConns))
+	return clientCtx, nil
+}
+
 func startGrpcServer(
 	ctx context.Context,
 	g *errgroup.Group,
@@ -479,7 +529,7 @@ func startGrpcServer(
 	}
 
 	// if gRPC is enabled, configure gRPC client for gRPC gateway
-	grpcClient, err := grpc.Dial( //nolint: staticcheck // ignore this line for this linter
+	grpcClient, err := grpc.NewClient(
 		config.Address,
 		grpc.WithTransportCredentials(insecure.NewCredentials()),
 		grpc.WithDefaultCallOptions(
@@ -495,6 +545,19 @@ func startGrpcServer(
 	clientCtx = clientCtx.WithGRPCClient(grpcClient)
 	svrCtx.Logger.Debug("gRPC client assigned to client context", "target", config.Address)
 
+	// Setup backup gRPC connections if configured
+	clientCtx, err = SetupBackupGRPCConnections(
+		clientCtx,
+		grpcClient,
+		config.BackupGRPCBlockAddressBlockRange,
+		maxRecvMsgSize,
+		maxSendMsgSize,
+		svrCtx.Logger,
+	)
+	if err != nil {
+		return nil, clientCtx, err
+	}
+
 	grpcSrv, err := servergrpc.NewGRPCServer(clientCtx, app, config)
 	if err != nil {
 		return nil, clientCtx, err
@@ -994,6 +1057,7 @@ func addStartNodeFlags(cmd *cobra.Command, opts StartCmdOptions) {
 	cmd.Flags().Bool(flagGRPCEnable, true, "Define if the gRPC server should be enabled")
 	cmd.Flags().String(flagGRPCAddress, serverconfig.DefaultGRPCAddress, "the gRPC server address to listen on")
 	cmd.Flags().Bool(flagGRPCWebEnable, true, "Define if the gRPC-Web server should be enabled. (Note: gRPC must also be enabled)")
+	cmd.Flags().String(flagBackupGRPCBlockAddressBlockRange, "", "Define if backup grpc and block range is available")
 	cmd.Flags().Uint64(FlagStateSyncSnapshotInterval, 0, "State sync snapshot interval")
 	cmd.Flags().Uint32(FlagStateSyncSnapshotKeepRecent, 2, "State sync snapshot to keep")
 	cmd.Flags().Bool(FlagDisableIAVLFastNode, false, "Disable fast node for IAVL tree")