Hard-code the state sync trust period per chain (#4679)

State sync's trust period has been a per-node `[statesync] trust-period`
setting, defaulting to 168h. It has to stay below the unbonding time so
that the validators who signed the trusted header are still slashable,
so cutting the unbonding time from 21 to 7 days
([CON-381](https://linear.app/seilabs/issue/CON-381/reduce-21-days-unbonding-time-to-7-days))
would depend on every operator editing their config.toml. A governance
param ([#4677](#4677),
closed) does not fit either: a node that state syncs cannot learn the
value without first trusting an RPC server for it. So the value now
lives in the binary.

`config.StateSyncTrustPeriod(chainID)` returns the period from a
per-chain table: 112h on pacific-1, atlantic-2 and arctic-1, which all
run a 21-day unbonding time today and stay below the planned 7 days, and
168h, the old default, on any other chain, such as the docker localnet.
`Reactor.initStateProvider` passes it to both the RPC and the P2P state
providers. The `TrustPeriod` field, its default and its `ValidateBasic`
check are removed from `StateSyncConfig`, and `trust-period` is removed
from the config.toml template and the docker configs.

Consensus and state are untouched, so no upgrade handler is needed; the
change should be backported to release/v6.8 so the whole network ships
the same value. A config.toml that still sets `trust-period` keeps
loading and the value is ignored, so an existing override stops
applying: a node that state synced from an old trust height under a
longer configured period now needs a trust height less than 112h old, or
it fails with `ErrOldHeaderExpired`.

`seid start` logs a warning when `trust-period` is still set to a value
other than the chain's built-in period, naming the chain ID, the
configured value and the period in use, so the ignored override does not
go unnoticed; nothing is logged for a matching value or an absent key.
The old template wrote `trust-period = "168h0m0s"`, so most existing
nodes on pacific-1, atlantic-2 and arctic-1 will log it on every start,
whether or not state sync is enabled, until the line is removed.

`seid tendermint light --trusting-period` keeps its own 168h flag
default. Validated with the `sei-tendermint/config`,
`internal/statesync` and `sei-cosmos/server` tests, the config
characterization suites in `cmd/seid/cmd` and `testutil/configtest`, and
a `seid start` on a pacific-1 home that still sets the old default.

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: alexander-sei

docker/localnode/config/config.toml

@@ -314,14 +314,10 @@ enable = false
 
 # RPC servers (comma-separated) for light client verification of the synced state machine and
 # retrieval of state data for node bootstrapping. Also needs a trusted height and corresponding
-# header hash obtained from a trusted source, and a period during which validators can be trusted.
-#
-# For Cosmos SDK-based chains, trust_period should usually be about 2/3 of the unbonding time (~2
-# weeks) during which they can be financially punished (slashed) for misbehavior.
+# header hash obtained from a trusted source.
 rpc-servers = ""
 trust-height = 0
 trust-hash = ""
-trust-period = "168h0m0s"
 
 # Time to spend discovering snapshots before initiating a restore.
 discovery-time = "15s"

docker/rpcnode/config/config.toml

@@ -314,14 +314,10 @@ enable = false
 
 # RPC servers (comma-separated) for light client verification of the synced state machine and
 # retrieval of state data for node bootstrapping. Also needs a trusted height and corresponding
-# header hash obtained from a trusted source, and a period during which validators can be trusted.
-#
-# For Cosmos SDK-based chains, trust_period should usually be about 2/3 of the unbonding time (~2
-# weeks) during which they can be financially punished (slashed) for misbehavior.
+# header hash obtained from a trusted source.
 rpc-servers = ""
 trust-height = 0
 trust-hash = ""
-trust-period = "168h0m0s"
 
 # Time to spend discovering snapshots before initiating a restore.
 discovery-time = "15s"

sei-cosmos/server/start.go

@@ -26,10 +26,12 @@ import (
 	genesistypes "github.com/sei-protocol/sei-chain/sei-cosmos/types/genesis"
 	"github.com/sei-protocol/sei-chain/sei-cosmos/utils/tracing"
 	tcmd "github.com/sei-protocol/sei-chain/sei-tendermint/cmd/tendermint/commands"
+	tmcfg "github.com/sei-protocol/sei-chain/sei-tendermint/config"
 	"github.com/sei-protocol/sei-chain/sei-tendermint/node"
 	"github.com/sei-protocol/sei-chain/sei-tendermint/rpc/client/local"
 	tmtypes "github.com/sei-protocol/sei-chain/sei-tendermint/types"
 	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
 	"go.opentelemetry.io/otel/sdk/trace"
 )
 
@@ -316,6 +318,7 @@ func startInProcess(
 	if ctx.Viper.GetBool("rosetta.enable") {
 		logger.Error("WARNING: rosetta.enable is set in app.toml, but seid no longer includes the Rosetta API server; the setting is ignored")
 	}
+	warnIgnoredStateSyncTrustPeriod(ctx.Viper, clientCtx.ChainID)
 	app := appCreator(nil, traceWriter, ctx.Config, ctx.Viper)
 	defer func() {
 		logger.Info("close any other open resource...")
@@ -417,3 +420,15 @@ func startInProcess(
 	// wait for signal capture and gracefully return
 	return WaitForQuitSignals(goCtx, restartCh)
 }
+
+// warnIgnoredStateSyncTrustPeriod logs a warning when v sets [statesync] trust-period to a
+// value other than the trust period state sync uses on chainID.
+func warnIgnoredStateSyncTrustPeriod(v *viper.Viper, chainID string) {
+	const key = "statesync.trust-period"
+	trustPeriod := tmcfg.StateSyncTrustPeriod(chainID)
+	if !v.IsSet(key) || v.GetDuration(key) == trustPeriod {
+		return
+	}
+	logger.Warn("statesync.trust-period is set in config.toml, but state sync uses the trust period built into seid for this chain; the setting is ignored and can be removed",
+		"chainID", chainID, "configured", v.GetString(key), "trustPeriod", trustPeriod.String())
+}

sei-cosmos/server/start_test.go

@@ -1,12 +1,19 @@
 package server
 
 import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"strings"
 	"testing"
 
 	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
 	"github.com/stretchr/testify/require"
 
 	"github.com/sei-protocol/sei-chain/sei-cosmos/telemetry"
+	tmcfg "github.com/sei-protocol/sei-chain/sei-tendermint/config"
 )
 
 func TestInjectTelemetryChainID(t *testing.T) {
@@ -59,3 +66,46 @@ func TestRemovedGRPCStartFlags(t *testing.T) {
 	// grpc-only meant "do not start Tendermint"; ignoring it would start a full node.
 	require.Error(t, cmd.ParseFlags([]string{"--grpc-only"}))
 }
+
+func TestWarnIgnoredStateSyncTrustPeriod(t *testing.T) {
+	for name, tc := range map[string]struct {
+		chainID     string
+		trustPeriod string // config.toml value; empty leaves the key out
+		wantWarning bool
+	}{
+		"unset":                            {chainID: "pacific-1"},
+		"matches the chain's period":       {chainID: "pacific-1", trustPeriod: "112h"},
+		"old default on pacific-1":         {chainID: "pacific-1", trustPeriod: "168h0m0s", wantWarning: true},
+		"old default on an unlisted chain": {chainID: "sei", trustPeriod: "168h0m0s"},
+		"override on an unlisted chain":    {chainID: "sei", trustPeriod: "72h", wantWarning: true},
+		"not a duration":                   {chainID: "sei", trustPeriod: "one week", wantWarning: true},
+	} {
+		t.Run(name, func(t *testing.T) {
+			configToml := "[statesync]\n"
+			if tc.trustPeriod != "" {
+				configToml += fmt.Sprintf("trust-period = %q\n", tc.trustPeriod)
+			}
+			v := viper.New()
+			v.SetConfigType("toml")
+			require.NoError(t, v.ReadConfig(strings.NewReader(configToml)))
+
+			logs := &bytes.Buffer{}
+			prev := logger
+			logger = slog.New(slog.NewJSONHandler(logs, nil))
+			t.Cleanup(func() { logger = prev })
+
+			warnIgnoredStateSyncTrustPeriod(v, tc.chainID)
+
+			if !tc.wantWarning {
+				require.Empty(t, logs.String())
+				return
+			}
+			var record map[string]any
+			require.NoError(t, json.Unmarshal(logs.Bytes(), &record))
+			require.Equal(t, slog.LevelWarn.String(), record[slog.LevelKey])
+			require.Equal(t, tc.chainID, record["chainID"])
+			require.Equal(t, tc.trustPeriod, record["configured"])
+			require.Equal(t, tmcfg.StateSyncTrustPeriod(tc.chainID).String(), record["trustPeriod"])
+		})
+	}
+}

sei-tendermint/config/config.go

@@ -1071,6 +1071,28 @@ func (cfg *MempoolConfig) ValidateBasic() error {
 //-----------------------------------------------------------------------------
 // StateSyncConfig
 
+// stateSyncTrustPeriods maps a well-known chain ID to its state sync trust period.
+var stateSyncTrustPeriods = map[string]time.Duration{
+	// A trust period plus the time needed to check headers and to report and
+	// punish misbehavior must stay below the network's unbonding time.
+	"pacific-1":  112 * time.Hour,
+	"atlantic-2": 112 * time.Hour,
+	"arctic-1":   112 * time.Hour,
+}
+
+// defaultStateSyncTrustPeriod is the state sync trust period of a chain that
+// stateSyncTrustPeriods does not list.
+const defaultStateSyncTrustPeriod = 168 * time.Hour
+
+// StateSyncTrustPeriod returns how long after its time a header of chainID can
+// still serve as the trusted root state sync verifies light blocks from.
+func StateSyncTrustPeriod(chainID string) time.Duration {
+	if trustPeriod, ok := stateSyncTrustPeriods[chainID]; ok {
+		return trustPeriod
+	}
+	return defaultStateSyncTrustPeriod
+}
+
 // StateSyncConfig defines the configuration for the Tendermint state sync service
 type StateSyncConfig struct {
 	// State sync rapidly bootstraps a new node by discovering, fetching, and restoring a
@@ -1090,15 +1112,11 @@ type StateSyncConfig struct {
 	// with net.Dial, for example: "host.example.com:2125".
 	RPCServers []string `mapstructure:"rpc-servers"`
 
-	// The hash and height of a trusted block. Must be within the trust-period.
+	// The hash and height of a trusted block. Must be within the trust period
+	// StateSyncTrustPeriod returns for the chain.
 	TrustHeight int64  `mapstructure:"trust-height"`
 	TrustHash   string `mapstructure:"trust-hash"`
 
-	// The trust period should be set so that Tendermint can detect and gossip
-	// misbehavior before it is considered expired. For chains based on the Cosmos SDK,
-	// one day less than the unbonding period should suffice.
-	TrustPeriod time.Duration `mapstructure:"trust-period"`
-
 	// Backfill sequentially fetches, verifies and stores light blocks in reverse order.
 	// It does not stop verifying blocks until reaching a height
 	// that is less or equal to the latestBlock - backfill-blocks and latest block time - backfill-duration.
@@ -1149,7 +1167,6 @@ func (cfg *StateSyncConfig) TrustHashBytes() []byte {
 // DefaultStateSyncConfig returns a default configuration for the state sync service
 func DefaultStateSyncConfig() *StateSyncConfig {
 	return &StateSyncConfig{
-		TrustPeriod:               168 * time.Hour,
 		DiscoveryTime:             15 * time.Second,
 		ChunkRequestTimeout:       15 * time.Second,
 		Fetchers:                  2,
@@ -1190,10 +1207,6 @@ func (cfg *StateSyncConfig) ValidateBasic() error {
 		return errors.New("discovery time must be 0s or greater than five seconds")
 	}
 
-	if cfg.TrustPeriod <= 0 {
-		return errors.New("trusted-period is required")
-	}
-
 	if cfg.TrustHeight <= 0 {
 		return errors.New("trusted-height is required")
 	}

sei-tendermint/config/config_test.go

@@ -141,6 +141,20 @@ func TestStateSyncConfigValidateBasic(t *testing.T) {
 	require.NoError(t, cfg.ValidateBasic())
 }
 
+func TestStateSyncTrustPeriod(t *testing.T) {
+	testcases := map[string]time.Duration{
+		"pacific-1":  112 * time.Hour,
+		"atlantic-2": 112 * time.Hour,
+		"arctic-1":   112 * time.Hour,
+		"sei":        168 * time.Hour,
+	}
+	for chainID, want := range testcases {
+		t.Run(chainID, func(t *testing.T) {
+			require.Equal(t, want, StateSyncTrustPeriod(chainID))
+		})
+	}
+}
+
 func TestConsensusConfig_ValidateBasic(t *testing.T) {
 	testcases := map[string]struct {
 		modify    func(*ConsensusConfig)

sei-tendermint/config/statesync_compat_test.go

@@ -75,7 +75,6 @@ enable = true
 rpc-servers = "localhost:26657,localhost:26659"
 trust-height = 10
 trust-hash = "AABB"
-trust-period = "168h0m0s"
 `), 0600)
 	require.NoError(t, err)
 
@@ -96,3 +95,28 @@ trust-period = "168h0m0s"
 
 	require.NoError(t, cfg.StateSync.ValidateBasic())
 }
+
+// TestStateSyncConfigIgnoresTrustPeriod pins that a config.toml which still sets
+// trust-period loads and validates, whatever value the key holds.
+func TestStateSyncConfigIgnoresTrustPeriod(t *testing.T) {
+	viper.Reset()
+	t.Cleanup(viper.Reset)
+
+	configPath := filepath.Join(t.TempDir(), "config.toml")
+	err := os.WriteFile(configPath, []byte(`
+[statesync]
+enable = true
+rpc-servers = "localhost:26657,localhost:26659"
+trust-height = 10
+trust-hash = "AABB"
+trust-period = "0s"
+`), 0600)
+	require.NoError(t, err)
+
+	viper.SetConfigFile(configPath)
+	require.NoError(t, viper.ReadInConfig())
+
+	cfg, err := commands.ParseConfig(tmconfig.DefaultConfig())
+	require.NoError(t, err)
+	require.NoError(t, cfg.StateSync.ValidateBasic())
+}

sei-tendermint/config/toml.go

@@ -527,15 +527,11 @@ use-p2p = {{ .StateSync.UseP2P }}
 # for example: "host.example.com:2125"
 rpc-servers = "{{ StringsJoin .StateSync.RPCServers "," }}"
 
-# The hash and height of a trusted block. Must be within the trust-period.
+# The hash and height of a trusted block. Must be within the chain's trust period, which is
+# built into the binary (112h on pacific-1, atlantic-2 and arctic-1).
 trust-height = {{ .StateSync.TrustHeight }}
 trust-hash = "{{ .StateSync.TrustHash }}"
 
-# The trust period should be set so that Tendermint can detect and gossip misbehavior before
-# it is considered expired. For chains based on the Cosmos SDK, one day less than the unbonding
-# period should suffice.
-trust-period = "{{ .StateSync.TrustPeriod }}"
-
 # Whether to use local snapshot only for state sync or not.
 # If this is true, then state sync will look for existing snapshots
 # which are located in the snapshot-dir configured in app.toml (default to [home-dir]/data/snapshots)

sei-tendermint/config/toml_test.go

@@ -99,6 +99,12 @@ func checkConfig(t *testing.T, configFile string) {
 		}
 	}
 
+	// The state sync trust period is built into the binary per chain, so the
+	// template must not offer a key for it. See StateSyncTrustPeriod.
+	if configContainsKey(configFile, "trust-period") {
+		t.Errorf("config file was not expected to contain trust-period")
+	}
+
 	// accept-interval is rendered deliberately: an accept rate too low to drain
 	// the kernel backlog silently stops a node acquiring inbound peers, and the
 	// template is where an operator looks. Keep it discoverable.

sei-tendermint/internal/statesync/reactor.go

@@ -268,7 +268,7 @@ func NewReactor(
 
 func (r *Reactor) initStateProvider(ctx context.Context, chainID string, initialHeight int64) error {
 	to := light.TrustOptions{
-		Period: r.cfg.TrustPeriod,
+		Period: config.StateSyncTrustPeriod(chainID),
 		Height: r.cfg.TrustHeight,
 		Hash:   r.cfg.TrustHashBytes(),
 	}