Merge PR cosmos#4059: Add support for graceful halt via server config

.pending/features/sdk/3981-Add-support-to-gracefully-halt-a-node-at-a-given-height

@@ -0,0 +1,2 @@
+#3981 Add support to gracefully halt a node at a given height
+via the node's `halt-height` config or CLI value.

baseapp/baseapp.go

@@ -3,6 +3,7 @@ package baseapp
 import (
 	"fmt"
 	"io"
+	"os"
 	"reflect"
 	"runtime/debug"
 	"strings"
@@ -81,6 +82,9 @@ type BaseApp struct {
 
 	// flag for sealing options and parameters to a BaseApp
 	sealed bool
+
+	// height at which to halt the chain and gracefully shutdown
+	haltHeight uint64
 }
 
 var _ abci.Application = (*BaseApp)(nil)
@@ -230,6 +234,10 @@ func (app *BaseApp) setMinGasPrices(gasPrices sdk.DecCoins) {
 	app.minGasPrices = gasPrices
 }
 
+func (app *BaseApp) setHaltHeight(height uint64) {
+	app.haltHeight = height
+}
+
 // Router returns the router of the BaseApp.
 func (app *BaseApp) Router() Router {
 	if app.sealed {
@@ -885,7 +893,13 @@ func (app *BaseApp) EndBlock(req abci.RequestEndBlock) (res abci.ResponseEndBloc
 	return
 }
 
-// Commit implements the ABCI interface.
+// Commit implements the ABCI interface. It will commit all state that exists in
+// the deliver state's multi-store and includes the resulting commit ID in the
+// returned abci.ResponseCommit. Commit will set the check state based on the
+// latest header and reset the deliver state. Also, if a non-zero halt height is
+// defined in config, Commit will execute a deferred function call to check
+// against that height and gracefully halt if it matches the latest committed
+// height.
 func (app *BaseApp) Commit() (res abci.ResponseCommit) {
 	header := app.deliverState.ctx.BlockHeader()
 
@@ -896,13 +910,20 @@ func (app *BaseApp) Commit() (res abci.ResponseCommit) {
 
 	// Reset the Check state to the latest committed.
 	//
-	// NOTE: safe because Tendermint holds a lock on the mempool for Commit.
-	// Use the header from this latest block.
+	// NOTE: This is safe because Tendermint holds a lock on the mempool for
+	// Commit. Use the header from this latest block.
 	app.setCheckState(header)
 
 	// empty/reset the deliver state
 	app.deliverState = nil
 
+	defer func() {
+		if app.haltHeight > 0 && uint64(header.Height) == app.haltHeight {
+			app.logger.Info("halting node per configuration", "height", app.haltHeight)
+			os.Exit(0)
+		}
+	}()
+
 	return abci.ResponseCommit{
 		Data: commitID.Hash,
 	}

baseapp/options.go

@@ -28,6 +28,11 @@ func SetMinGasPrices(gasPricesStr string) func(*BaseApp) {
 	return func(bap *BaseApp) { bap.setMinGasPrices(gasPrices) }
 }
 
+// SetHaltHeight returns a BaseApp option function that sets the halt height.
+func SetHaltHeight(height uint64) func(*BaseApp) {
+	return func(bap *BaseApp) { bap.setHaltHeight(height) }
+}
+
 func (app *BaseApp) SetName(name string) {
 	if app.sealed {
 		panic("SetName() on sealed BaseApp")

cmd/gaia/cmd/gaiad/main.go

@@ -70,6 +70,7 @@ func newApp(logger log.Logger, db dbm.DB, traceStore io.Writer) abci.Application
 		logger, db, traceStore, true, invCheckPeriod,
 		baseapp.SetPruning(store.NewPruningOptionsFromString(viper.GetString("pruning"))),
 		baseapp.SetMinGasPrices(viper.GetString(server.FlagMinGasPrices)),
+		baseapp.SetHaltHeight(uint64(viper.GetInt(server.FlagHaltHeight))),
 	)
 }
 

cmd/gaia/init/testnet.go

@@ -236,6 +236,8 @@ func initTestnet(config *tmconfig.Config, cdc *codec.Codec) error {
 			return err
 		}
 
+		// TODO: Rename config file to server.toml as it's not particular to Gaia
+		// (REF: https://github.com/cosmos/cosmos-sdk/issues/4125).
 		gaiaConfigFilePath := filepath.Join(nodeDir, "config/gaiad.toml")
 		srvconfig.WriteConfigFile(gaiaConfigFilePath, gaiaConfig)
 	}

docs/cosmos-hub/validators/validator-setup.md

@@ -165,6 +165,15 @@ You should now see your validator in one of the Cosmos Hub explorers. You are lo
 To be in the validator set, you need to have more total voting power than the 100th validator.
 :::
 
+## Halting Your Validator
+
+When attempting to perform routine maintenance or planning for an upcoming coordinated
+upgrade, it can be useful to have your validator systematically and gracefully halt.
+You can achieve this by either setting the `halt-height` to the height at which
+you want your node to shutdown or by passing the `--halt-height` flag to `gaiad`.
+The node will shutdown with a zero exit code at that given height after committing
+the block.
+
 ## Common Problems
 
 ### Problem #1: My validator has `voting_power: 0`

server/config/config.go

@@ -17,6 +17,10 @@ type BaseConfig struct {
 	// transaction. A transaction's fees must meet the minimum of any denomination
 	// specified in this config (e.g. 0.25token1;0.0001token2).
 	MinGasPrices string `mapstructure:"minimum-gas-prices"`
+
+	// HaltHeight contains a non-zero height at which a node will gracefully halt
+	// and shutdown that can be used to assist upgrades and testing.
+	HaltHeight uint64 `mapstructure:"halt-height"`
 }
 
 // Config defines the server's top level configuration
@@ -56,6 +60,7 @@ func DefaultConfig() *Config {
 	return &Config{
 		BaseConfig{
 			MinGasPrices: defaultMinGasPrices,
+			HaltHeight:   0,
 		},
 	}
 }

server/config/toml.go

@@ -17,6 +17,10 @@ const defaultConfigTemplate = `# This is a TOML config file.
 # transaction. A transaction's fees must meet the minimum of any denomination
 # specified in this config (e.g. 0.25token1;0.0001token2).
 minimum-gas-prices = "{{ .BaseConfig.MinGasPrices }}"
+
+# HaltHeight contains a non-zero height at which a node will gracefully halt
+# and shutdown that can be used to assist upgrades and testing.
+halt-height = {{ .BaseConfig.HaltHeight }}
 `
 
 var configTemplate *template.Template

server/start.go

@@ -23,6 +23,7 @@ const (
 	flagTraceStore     = "trace-store"
 	flagPruning        = "pruning"
 	FlagMinGasPrices   = "minimum-gas-prices"
+	FlagHaltHeight     = "halt-height"
 )
 
 // StartCmd runs the service passed in, either stand-alone or in-process with
@@ -53,6 +54,7 @@ func StartCmd(ctx *Context, appCreator AppCreator) *cobra.Command {
 		FlagMinGasPrices, "",
 		"Minimum gas prices to accept for transactions; Any fee in a tx must meet this minimum (e.g. 0.01photino;0.0001stake)",
 	)
+	cmd.Flags().Uint64(FlagHaltHeight, 0, "Height at which to gracefully halt the chain and shutdown the node")
 
 	// add support for all Tendermint-specific command line options
 	tcmd.AddNodeFlags(cmd)

server/util.go

@@ -105,7 +105,10 @@ func interceptLoadConfig() (conf *cfg.Config, err error) {
 		conf, err = tcmd.ParseConfig() // NOTE: ParseConfig() creates dir/files as necessary.
 	}
 
-	// create a default gaia config file if it does not exist
+	// create a default Gaia config file if it does not exist
+	//
+	// TODO: Rename config file to server.toml as it's not particular to Gaia
+	// (REF: https://github.com/cosmos/cosmos-sdk/issues/4125).
 	gaiaConfigFilePath := filepath.Join(rootDir, "config/gaiad.toml")
 	if _, err := os.Stat(gaiaConfigFilePath); os.IsNotExist(err) {
 		gaiaConf, _ := config.ParseConfig()