rename configuration parameters to use the new blocksync nomenclature (#6896)

The 0.35 release cycle renamed the 'fastsync' functionality to 'blocksync'. This change brings the configuration parameters in line with that change. Namely, it updates the configuration file `[fastsync]` field to be `[blocksync]` and changes the command line flag and config file parameters `--fast-sync` and `fast-sync` to `--enable-block-sync` and `enable-block-sync` respectively.

Error messages were added to help users encountering these changes be able to quickly make the needed update to their files/scripts.

When using the old command line argument for fast-sync, the following is printed

```
./build/tendermint start --proxy-app=kvstore --consensus.create-empty-blocks=false --fast-sync=false
ERROR: invalid argument "false" for "--fast-sync" flag: --fast-sync has been deprecated, please use --enable-block-sync
```

When using one of the old config file parameters, the following is printed:
```
./build/tendermint start --proxy-app=kvstore --consensus.create-empty-blocks=false
ERROR: error in config file: a configuration parameter named 'fast-sync' was found in the configuration file. The 'fast-sync' parameter has been renamed to 'enable-block-sync', please update the 'fast-sync' field in your configuration file to 'enable-block-sync'
```

UPGRADING.md

@@ -17,10 +17,16 @@ This guide provides instructions for upgrading to specific versions of Tendermin
 
 ### Config Changes
 
-* The configuration variable `fast-sync` and flag `--fast-sync` have been renamed to `enable-block-sync` and `--enable-block-sync`
-  and the configuration field `[fastsync]` has been renamed to `[blocksync]`.
+* The configuration file field `[fastsync]` has been renamed to `[blocksync]`.
+
+* The top level configuration file field `fast-sync` has moved under the new `[blocksync]`
+  field as `blocksync.enable`.
+
+* `blocksync.version = "v1"` and `blocksync.version = "v2"` (previously `fastsync`)
+  are no longer supported. Please use `v0` instead. During the v0.35 release cycle, `v0` was
+  determined to suit the existing needs and the cost of maintaining the `v1` and `v2` modules
+  was determined to be greater than necessary.
 
-* `blocksync.version = "v1"` and `blocksync.version = "v2"` (previously `fastsync`) are no longer supported. Please use `v0` instead.
 
 * All config parameters are now hyphen-case (also known as kebab-case) instead of snake_case. Before restarting the node make sure
   you have updated all the variables in your `config.toml` file.
@@ -63,6 +69,8 @@ if needed.
 
 * You must now specify the node mode (validator|full|seed) in `tendermint init [mode]`
 
+* The `--fast-sync` command line option has been renamed to `--blocksync.enable`
+
 * If you had previously used `tendermint gen_node_key` to generate a new node
   key, keep in mind that it no longer saves the output to a file. You can use
   `tendermint init validator` or pipe the output of `tendermint gen_node_key` to

cmd/tendermint/commands/run_node.go

@@ -3,6 +3,8 @@ package commands
 import (
 	"bytes"
 	"crypto/sha256"
+	"errors"
+	"flag"
 	"fmt"
 	"io"
 	"os"
@@ -33,7 +35,22 @@ func AddNodeFlags(cmd *cobra.Command) {
 		"socket address to listen on for connections from external priv-validator process")
 
 	// node flags
-	cmd.Flags().Bool("fast-sync", config.FastSyncMode, "fast blockchain syncing")
+	cmd.Flags().Bool("blocksync.enable", config.BlockSync.Enable, "enable fast blockchain syncing")
+
+	// TODO (https://github.com/tendermint/tendermint/issues/6908): remove this check after the v0.35 release cycle
+	// This check was added to give users an upgrade prompt to use the new flag for syncing.
+	//
+	// The pflag package does not have a native way to print a depcrecation warning
+	// and return an error. This logic was added to print a deprecation message to the user
+	// and then crash if the user attempts to use the old --fast-sync flag.
+	fs := flag.NewFlagSet("", flag.ExitOnError)
+	fs.Func("fast-sync", "deprecated",
+		func(string) error {
+			return errors.New("--fast-sync has been deprecated, please use --blocksync.enable")
+		})
+	cmd.Flags().AddGoFlagSet(fs)
+
+	cmd.Flags().MarkHidden("fast-sync") //nolint:errcheck
 	cmd.Flags().BytesHexVar(
 		&genesisHash,
 		"genesis-hash",
@@ -158,7 +175,7 @@ func checkGenesisHash(config *cfg.Config) error {
 	// Compare with the flag.
 	if !bytes.Equal(genesisHash, actualHash) {
 		return fmt.Errorf(
-			"--genesis_hash=%X does not match %s hash: %X",
+			"--genesis-hash=%X does not match %s hash: %X",
 			genesisHash, config.GenesisFile(), actualHash)
 	}
 

config/config.go

@@ -76,7 +76,7 @@ type Config struct {
 	P2P             *P2PConfig             `mapstructure:"p2p"`
 	Mempool         *MempoolConfig         `mapstructure:"mempool"`
 	StateSync       *StateSyncConfig       `mapstructure:"statesync"`
-	BlockSync       *BlockSyncConfig       `mapstructure:"fastsync"`
+	BlockSync       *BlockSyncConfig       `mapstructure:"blocksync"`
 	Consensus       *ConsensusConfig       `mapstructure:"consensus"`
 	TxIndex         *TxIndexConfig         `mapstructure:"tx-index"`
 	Instrumentation *InstrumentationConfig `mapstructure:"instrumentation"`
@@ -152,7 +152,7 @@ func (cfg *Config) ValidateBasic() error {
 		return fmt.Errorf("error in [statesync] section: %w", err)
 	}
 	if err := cfg.BlockSync.ValidateBasic(); err != nil {
-		return fmt.Errorf("error in [fastsync] section: %w", err)
+		return fmt.Errorf("error in [blocksync] section: %w", err)
 	}
 	if err := cfg.Consensus.ValidateBasic(); err != nil {
 		return fmt.Errorf("error in [consensus] section: %w", err)
@@ -194,12 +194,6 @@ type BaseConfig struct { //nolint: maligned
 	//   - No priv_validator_key.json, priv_validator_state.json
 	Mode string `mapstructure:"mode"`
 
-	// If this node is many blocks behind the tip of the chain, FastSync
-	// allows them to catchup quickly by downloading blocks in parallel
-	// and verifying their commits
-	// TODO: This should be moved to the blocksync config
-	FastSyncMode bool `mapstructure:"fast-sync"`
-
 	// Database backend: goleveldb | cleveldb | boltdb | rocksdb
 	// * goleveldb (github.com/syndtr/goleveldb - most popular implementation)
 	//   - pure go
@@ -242,23 +236,24 @@ type BaseConfig struct { //nolint: maligned
 	// If true, query the ABCI app on connecting to a new peer
 	// so the app can decide if we should keep the connection or not
 	FilterPeers bool `mapstructure:"filter-peers"` // false
+
+	Other map[string]interface{} `mapstructure:",remain"`
 }
 
 // DefaultBaseConfig returns a default base configuration for a Tendermint node
 func DefaultBaseConfig() BaseConfig {
 	return BaseConfig{
-		Genesis:      defaultGenesisJSONPath,
-		NodeKey:      defaultNodeKeyPath,
-		Mode:         defaultMode,
-		Moniker:      defaultMoniker,
-		ProxyApp:     "tcp://127.0.0.1:26658",
-		ABCI:         "socket",
-		LogLevel:     DefaultLogLevel,
-		LogFormat:    log.LogFormatPlain,
-		FastSyncMode: true,
-		FilterPeers:  false,
-		DBBackend:    "goleveldb",
-		DBPath:       "data",
+		Genesis:     defaultGenesisJSONPath,
+		NodeKey:     defaultNodeKeyPath,
+		Mode:        defaultMode,
+		Moniker:     defaultMoniker,
+		ProxyApp:    "tcp://127.0.0.1:26658",
+		ABCI:        "socket",
+		LogLevel:    DefaultLogLevel,
+		LogFormat:   log.LogFormatPlain,
+		FilterPeers: false,
+		DBBackend:   "goleveldb",
+		DBPath:      "data",
 	}
 }
 
@@ -268,7 +263,6 @@ func TestBaseConfig() BaseConfig {
 	cfg.chainID = "tendermint_test"
 	cfg.Mode = ModeValidator
 	cfg.ProxyApp = "kvstore"
-	cfg.FastSyncMode = false
 	cfg.DBBackend = "memdb"
 	return cfg
 }
@@ -345,6 +339,28 @@ func (cfg BaseConfig) ValidateBasic() error {
 		return fmt.Errorf("unknown mode: %v", cfg.Mode)
 	}
 
+	// TODO (https://github.com/tendermint/tendermint/issues/6908) remove this check after the v0.35 release cycle.
+	// This check was added to give users an upgrade prompt to use the new
+	// configuration option in v0.35. In future release cycles they should no longer
+	// be using this configuration parameter so the check can be removed.
+	// The cfg.Other field can likely be removed at the same time if it is not referenced
+	// elsewhere as it was added to service this check.
+	if fs, ok := cfg.Other["fastsync"]; ok {
+		if _, ok := fs.(map[string]interface{}); ok {
+			return fmt.Errorf("a configuration section named 'fastsync' was found in the " +
+				"configuration file. The 'fastsync' section has been renamed to " +
+				"'blocksync', please update the 'fastsync' field in your configuration file to 'blocksync'")
+		}
+	}
+	if fs, ok := cfg.Other["fast-sync"]; ok {
+		if fs != "" {
+			return fmt.Errorf("a parameter named 'fast-sync' was found in the " +
+				"configuration file. The parameter to enable or disable quickly syncing with a blockchain" +
+				"has moved to the [blocksync] section of the configuration file as blocksync.enable. " +
+				"Please move the 'fast-sync' field in your configuration file to 'blocksync.enable'")
+		}
+	}
+
 	return nil
 }
 
@@ -1005,13 +1021,18 @@ func (cfg *StateSyncConfig) ValidateBasic() error {
 //-----------------------------------------------------------------------------
 
 // BlockSyncConfig (formerly known as FastSync) defines the configuration for the Tendermint block sync service
+// If this node is many blocks behind the tip of the chain, BlockSync
+// allows them to catchup quickly by downloading blocks in parallel
+// and verifying their commits.
 type BlockSyncConfig struct {
+	Enable  bool   `mapstructure:"enable"`
 	Version string `mapstructure:"version"`
 }
 
 // DefaultBlockSyncConfig returns a default configuration for the block sync service
 func DefaultBlockSyncConfig() *BlockSyncConfig {
 	return &BlockSyncConfig{
+		Enable:  true,
 		Version: BlockSyncV0,
 	}
 }

config/toml.go

@@ -97,11 +97,6 @@ moniker = "{{ .BaseConfig.Moniker }}"
 #   - No priv_validator_key.json, priv_validator_state.json
 mode = "{{ .BaseConfig.Mode }}"
 
-# If this node is many blocks behind the tip of the chain, FastSync
-# allows them to catchup quickly by downloading blocks in parallel
-# and verifying their commits
-fast-sync = {{ .BaseConfig.FastSyncMode }}
-
 # Database backend: goleveldb | cleveldb | boltdb | rocksdb | badgerdb
 # * goleveldb (github.com/syndtr/goleveldb - most popular implementation)
 #   - pure go
@@ -465,10 +460,15 @@ fetchers = "{{ .StateSync.Fetchers }}"
 #######################################################
 ###       Block Sync Configuration Connections       ###
 #######################################################
-[fastsync]
+[blocksync]
+
+# If this node is many blocks behind the tip of the chain, BlockSync
+# allows them to catchup quickly by downloading blocks in parallel
+# and verifying their commits
+enable = {{ .BlockSync.Enable }}
 
 # Block Sync version to use:
-#   1) "v0" (default) - the legacy block sync implementation
+#   1) "v0" (default) - the standard Block Sync implementation
 #   2) "v2" - DEPRECATED, please use v0
 version = "{{ .BlockSync.Version }}"
 

config/toml_test.go

@@ -36,9 +36,7 @@ func TestEnsureRoot(t *testing.T) {
 	data, err := ioutil.ReadFile(filepath.Join(tmpDir, defaultConfigFilePath))
 	require.Nil(err)
 
-	if !checkConfig(string(data)) {
-		t.Fatalf("config file missing some information")
-	}
+	checkConfig(t, string(data))
 
 	ensureFiles(t, tmpDir, "data")
 }
@@ -57,9 +55,7 @@ func TestEnsureTestRoot(t *testing.T) {
 	data, err := ioutil.ReadFile(filepath.Join(rootDir, defaultConfigFilePath))
 	require.Nil(err)
 
-	if !checkConfig(string(data)) {
-		t.Fatalf("config file missing some information")
-	}
+	checkConfig(t, string(data))
 
 	// TODO: make sure the cfg returned and testconfig are the same!
 	baseConfig := DefaultBaseConfig()
@@ -67,16 +63,15 @@ func TestEnsureTestRoot(t *testing.T) {
 	ensureFiles(t, rootDir, defaultDataDir, baseConfig.Genesis, pvConfig.Key, pvConfig.State)
 }
 
-func checkConfig(configFile string) bool {
-	var valid bool
-
+func checkConfig(t *testing.T, configFile string) {
+	t.Helper()
 	// list of words we expect in the config
 	var elems = []string{
 		"moniker",
 		"seeds",
 		"proxy-app",
-		"fast_sync",
-		"create_empty_blocks",
+		"blocksync",
+		"create-empty-blocks",
 		"peer",
 		"timeout",
 		"broadcast",
@@ -89,10 +84,7 @@ func checkConfig(configFile string) bool {
 	}
 	for _, e := range elems {
 		if !strings.Contains(configFile, e) {
-			valid = false
-		} else {
-			valid = true
+			t.Errorf("config file was expected to contain %s but did not", e)
 		}
 	}
-	return valid
 }

docs/nodes/configuration.md

@@ -36,10 +36,6 @@ proxy-app = "tcp://127.0.0.1:26658"
 # A custom human readable name for this node
 moniker = "anonymous"
 
-# If this node is many blocks behind the tip of the chain, BlockSync
-# allows them to catchup quickly by downloading blocks in parallel
-# and verifying their commits
-fast-sync = true
 
 # Mode of Node: full | validator | seed (default: "validator")
 # * validator node (default)
@@ -356,11 +352,16 @@ temp-dir = ""
 #######################################################
 ###       BlockSync Configuration Connections       ###
 #######################################################
-[fastsync]
+[blocksync]
+
+# If this node is many blocks behind the tip of the chain, BlockSync
+# allows them to catchup quickly by downloading blocks in parallel
+# and verifying their commits
+enable = true
 
 # Block Sync version to use:
-#   1) "v0" (default) - the legacy block sync implementation
-#   2) "v2" - complete redesign of v0, optimized for testability & readability
+#   1) "v0" (default) - the standard block sync implementation
+#   2) "v2" - DEPRECATED, please use v0
 version = "v0"
 
 #######################################################

docs/tendermint-core/block-sync.md

@@ -17,9 +17,9 @@ consensus gossip protocol.
 
 ## Using Block Sync
 
-To support faster syncing, Tendermint offers a `fast-sync` mode, which
+To support faster syncing, Tendermint offers a `blocksync` mode, which
 is enabled by default, and can be toggled in the `config.toml` or via
-`--fast_sync=false`.
+`--blocksync.enable=false`.
 
 In this mode, the Tendermint daemon will sync hundreds of times faster
 than if it used the real-time consensus process. Once caught up, the
@@ -29,18 +29,23 @@ has at least one peer and it's height is at least as high as the max
 reported peer height. See [the IsCaughtUp
 method](https://github.com/tendermint/tendermint/blob/b467515719e686e4678e6da4e102f32a491b85a0/blockchain/pool.go#L128).
 
-Note: There are two versions of Block Sync. We recommend using v0 as v2 is still in beta.
+Note: There are multiple versions of Block Sync. Please use v0 as the other versions are no longer supported.
   If you would like to use a different version you can do so by changing the version in the `config.toml`:
 
 ```toml
 #######################################################
 ###       Block Sync Configuration Connections       ###
 #######################################################
-[fastsync]
+[blocksync]
+
+# If this node is many blocks behind the tip of the chain, BlockSync
+# allows them to catchup quickly by downloading blocks in parallel
+# and verifying their commits
+enable = true
 
 # Block Sync version to use:
-#   1) "v0" (default) - the legacy Block Sync implementation
-#   2) "v2" - complete redesign of v0, optimized for testability & readability
+#   1) "v0" (default) - the standard Block Sync implementation
+#   2) "v2" - DEPRECATED, please use v0
 version = "v0"
 ```
 
@@ -55,4 +60,4 @@ the network best height, it will switches to the state sync mechanism and then e
 another event for exposing the fast-sync `complete` status and the state `height`.
 
 The user can query the events by subscribing `EventQueryBlockSyncStatus`
-Please check [types](https://pkg.go.dev/github.com/tendermint/tendermint/types?utm_source=godoc#pkg-constants) for the details.
+Please check [types](https://pkg.go.dev/github.com/tendermint/tendermint/types?utm_source=godoc#pkg-constants) for the details.

go.mod

@@ -31,6 +31,7 @@ require (
 	github.com/sasha-s/go-deadlock v0.2.1-0.20190427202633-1595213edefa
 	github.com/snikch/goodman v0.0.0-20171125024755-10e37e294daa
 	github.com/spf13/cobra v1.2.1
+	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/spf13/viper v1.8.1
 	github.com/stretchr/testify v1.7.0
 	github.com/tendermint/tm-db v0.6.4

node/node.go

@@ -220,7 +220,7 @@ func makeNode(config *cfg.Config,
 
 	// Determine whether we should do block sync. This must happen after the handshake, since the
 	// app may modify the validator set, specifying ourself as the only validator.
-	blockSync := config.FastSyncMode && !onlyValidatorIsUs(state, pubKey)
+	blockSync := config.BlockSync.Enable && !onlyValidatorIsUs(state, pubKey)
 
 	logNodeStartupInfo(state, pubKey, logger, consensusLogger, config.Mode)
 
@@ -716,7 +716,7 @@ func (n *nodeImpl) OnStart() error {
 			// TODO: Some form of orchestrator is needed here between the state
 			// advancing reactors to be able to control which one of the three
 			// is running
-			if n.config.FastSyncMode {
+			if n.config.BlockSync.Enable {
 				// FIXME Very ugly to have these metrics bleed through here.
 				n.consensusReactor.SetBlockSyncingMetrics(1)
 				if err := bcR.SwitchToBlockSync(state); err != nil {

test/e2e/runner/setup.go

@@ -297,7 +297,7 @@ func MakeConfig(node *e2e.Node) (*config.Config, error) {
 	}
 
 	if node.BlockSync == "" {
-		cfg.FastSyncMode = false
+		cfg.BlockSync.Enable = false
 	} else {
 		cfg.BlockSync.Version = node.BlockSync
 	}