[Prototype] FoundationDB

.gitignore

@@ -4,6 +4,7 @@ release/
 .idea/
 .vscode/
 .DS_Store
+.worktree/
 build/
 cache/
 *.iml
@@ -64,4 +65,4 @@ sei-db/state_db/bench/cryptosim/data/**
 sei-db/state_db/bench/cryptosim/bin/
 sei-db/state_db/bench/cryptosim/logs/
 sei-db/ledger_db/block/blocksim/bin/
-sei-db/db_engine/litt/bin/
+sei-db/db_engine/litt/bin/

app/seidb.go

@@ -45,6 +45,24 @@ const (
 	FlagEVMSSSplit       = "state-store.evm-ss-split"
 	FlagEVMSSSeparateDBs = "state-store.evm-ss-separate-dbs"
 
+	// Historical SS offload fallback.
+	FlagHistoricalOffloadScyllaHosts                            = "state-store.historical-offload-scylla-hosts"
+	FlagHistoricalOffloadScyllaKeyspace                         = "state-store.historical-offload-scylla-keyspace"
+	FlagHistoricalOffloadScyllaUsername                         = "state-store.historical-offload-scylla-username"
+	FlagHistoricalOffloadScyllaPassword                         = "state-store.historical-offload-scylla-password"
+	FlagHistoricalOffloadScyllaDatacenter                       = "state-store.historical-offload-scylla-datacenter"
+	FlagHistoricalOffloadScyllaConsistency                      = "state-store.historical-offload-scylla-consistency"
+	FlagHistoricalOffloadScyllaTimeoutMS                        = "state-store.historical-offload-scylla-timeout-ms"
+	FlagHistoricalOffloadFoundationDBEnabled                    = "state-store.historical-offload-foundationdb-enabled"
+	FlagHistoricalOffloadFoundationDBClusterFile                = "state-store.historical-offload-foundationdb-cluster-file"
+	FlagHistoricalOffloadFoundationDBPrefix                     = "state-store.historical-offload-foundationdb-prefix"
+	FlagHistoricalOffloadFoundationDBAPIVersion                 = "state-store.historical-offload-foundationdb-api-version"
+	FlagHistoricalOffloadFoundationDBShards                     = "state-store.historical-offload-foundationdb-shards"
+	FlagHistoricalOffloadFoundationDBTransactionTimeoutMS       = "state-store.historical-offload-foundationdb-transaction-timeout-ms"
+	FlagHistoricalOffloadFoundationDBTransactionRetryLimit      = "state-store.historical-offload-foundationdb-transaction-retry-limit"
+	FlagHistoricalOffloadFoundationDBTransactionMaxRetryDelayMS = "state-store.historical-offload-foundationdb-transaction-max-retry-delay-ms"
+	FlagHistoricalOffloadFoundationDBTransactionSizeLimitBytes  = "state-store.historical-offload-foundationdb-transaction-size-limit-bytes"
+
 	// Other configs
 	FlagSnapshotInterval = "state-sync.snapshot-interval"
 )
@@ -148,6 +166,22 @@ func parseSSConfigs(appOpts servertypes.AppOptions) config.StateStoreConfig {
 	ssConfig.EVMDBDirectory = cast.ToString(appOpts.Get(FlagEVMSSDirectory))
 	ssConfig.SeparateEVMSubDBs = cast.ToBool(appOpts.Get(FlagEVMSSSeparateDBs))
 	ssConfig.EVMSplit = cast.ToBool(appOpts.Get(FlagEVMSSSplit))
+	ssConfig.HistoricalOffloadScyllaHosts = cast.ToString(appOpts.Get(FlagHistoricalOffloadScyllaHosts))
+	ssConfig.HistoricalOffloadScyllaKeyspace = cast.ToString(appOpts.Get(FlagHistoricalOffloadScyllaKeyspace))
+	ssConfig.HistoricalOffloadScyllaUsername = cast.ToString(appOpts.Get(FlagHistoricalOffloadScyllaUsername))
+	ssConfig.HistoricalOffloadScyllaPassword = cast.ToString(appOpts.Get(FlagHistoricalOffloadScyllaPassword))
+	ssConfig.HistoricalOffloadScyllaDatacenter = cast.ToString(appOpts.Get(FlagHistoricalOffloadScyllaDatacenter))
+	ssConfig.HistoricalOffloadScyllaConsistency = cast.ToString(appOpts.Get(FlagHistoricalOffloadScyllaConsistency))
+	ssConfig.HistoricalOffloadScyllaTimeoutMS = cast.ToInt(appOpts.Get(FlagHistoricalOffloadScyllaTimeoutMS))
+	ssConfig.HistoricalOffloadFoundationDBEnabled = cast.ToBool(appOpts.Get(FlagHistoricalOffloadFoundationDBEnabled))
+	ssConfig.HistoricalOffloadFoundationDBClusterFile = cast.ToString(appOpts.Get(FlagHistoricalOffloadFoundationDBClusterFile))
+	ssConfig.HistoricalOffloadFoundationDBPrefix = cast.ToString(appOpts.Get(FlagHistoricalOffloadFoundationDBPrefix))
+	ssConfig.HistoricalOffloadFoundationDBAPIVersion = cast.ToInt(appOpts.Get(FlagHistoricalOffloadFoundationDBAPIVersion))
+	ssConfig.HistoricalOffloadFoundationDBShards = cast.ToInt(appOpts.Get(FlagHistoricalOffloadFoundationDBShards))
+	ssConfig.HistoricalOffloadFoundationDBTransactionTimeoutMS = cast.ToInt(appOpts.Get(FlagHistoricalOffloadFoundationDBTransactionTimeoutMS))
+	ssConfig.HistoricalOffloadFoundationDBTransactionRetryLimit = cast.ToInt(appOpts.Get(FlagHistoricalOffloadFoundationDBTransactionRetryLimit))
+	ssConfig.HistoricalOffloadFoundationDBTransactionMaxRetryDelayMS = cast.ToInt(appOpts.Get(FlagHistoricalOffloadFoundationDBTransactionMaxRetryDelayMS))
+	ssConfig.HistoricalOffloadFoundationDBTransactionSizeLimitBytes = cast.ToInt(appOpts.Get(FlagHistoricalOffloadFoundationDBTransactionSizeLimitBytes))
 	return ssConfig
 }
 

app/seidb_test.go

@@ -61,6 +61,38 @@ func (t TestSeiDBAppOpts) Get(s string) interface{} {
 		return defaultSSConfig.EVMSplit
 	case FlagEVMSSSeparateDBs:
 		return defaultSSConfig.SeparateEVMSubDBs
+	case FlagHistoricalOffloadScyllaHosts:
+		return defaultSSConfig.HistoricalOffloadScyllaHosts
+	case FlagHistoricalOffloadScyllaKeyspace:
+		return defaultSSConfig.HistoricalOffloadScyllaKeyspace
+	case FlagHistoricalOffloadScyllaUsername:
+		return defaultSSConfig.HistoricalOffloadScyllaUsername
+	case FlagHistoricalOffloadScyllaPassword:
+		return defaultSSConfig.HistoricalOffloadScyllaPassword
+	case FlagHistoricalOffloadScyllaDatacenter:
+		return defaultSSConfig.HistoricalOffloadScyllaDatacenter
+	case FlagHistoricalOffloadScyllaConsistency:
+		return defaultSSConfig.HistoricalOffloadScyllaConsistency
+	case FlagHistoricalOffloadScyllaTimeoutMS:
+		return defaultSSConfig.HistoricalOffloadScyllaTimeoutMS
+	case FlagHistoricalOffloadFoundationDBEnabled:
+		return defaultSSConfig.HistoricalOffloadFoundationDBEnabled
+	case FlagHistoricalOffloadFoundationDBClusterFile:
+		return defaultSSConfig.HistoricalOffloadFoundationDBClusterFile
+	case FlagHistoricalOffloadFoundationDBPrefix:
+		return defaultSSConfig.HistoricalOffloadFoundationDBPrefix
+	case FlagHistoricalOffloadFoundationDBAPIVersion:
+		return defaultSSConfig.HistoricalOffloadFoundationDBAPIVersion
+	case FlagHistoricalOffloadFoundationDBShards:
+		return defaultSSConfig.HistoricalOffloadFoundationDBShards
+	case FlagHistoricalOffloadFoundationDBTransactionTimeoutMS:
+		return defaultSSConfig.HistoricalOffloadFoundationDBTransactionTimeoutMS
+	case FlagHistoricalOffloadFoundationDBTransactionRetryLimit:
+		return defaultSSConfig.HistoricalOffloadFoundationDBTransactionRetryLimit
+	case FlagHistoricalOffloadFoundationDBTransactionMaxRetryDelayMS:
+		return defaultSSConfig.HistoricalOffloadFoundationDBTransactionMaxRetryDelayMS
+	case FlagHistoricalOffloadFoundationDBTransactionSizeLimitBytes:
+		return defaultSSConfig.HistoricalOffloadFoundationDBTransactionSizeLimitBytes
 	}
 	return nil
 }
@@ -114,6 +146,58 @@ func TestParseSSConfigs_EVMFlags(t *testing.T) {
 	assert.True(t, ssConfig.SeparateEVMSubDBs)
 }
 
+func TestParseSSConfigs_HistoricalScyllaFlags(t *testing.T) {
+	appOpts := mapAppOpts{
+		FlagSSEnable:                           true,
+		FlagHistoricalOffloadScyllaHosts:       "10.0.0.1:9042,10.0.0.2:9042",
+		FlagHistoricalOffloadScyllaKeyspace:    "sei_history",
+		FlagHistoricalOffloadScyllaUsername:    "sei",
+		FlagHistoricalOffloadScyllaPassword:    "secret",
+		FlagHistoricalOffloadScyllaDatacenter:  "use1",
+		FlagHistoricalOffloadScyllaConsistency: "local_quorum",
+		FlagHistoricalOffloadScyllaTimeoutMS:   1500,
+		FlagSSAsyncWriterBuffer:                0,
+	}
+
+	ssConfig := parseSSConfigs(appOpts)
+	assert.True(t, ssConfig.Enable)
+	assert.Equal(t, "10.0.0.1:9042,10.0.0.2:9042", ssConfig.HistoricalOffloadScyllaHosts)
+	assert.Equal(t, "sei_history", ssConfig.HistoricalOffloadScyllaKeyspace)
+	assert.Equal(t, "sei", ssConfig.HistoricalOffloadScyllaUsername)
+	assert.Equal(t, "secret", ssConfig.HistoricalOffloadScyllaPassword)
+	assert.Equal(t, "use1", ssConfig.HistoricalOffloadScyllaDatacenter)
+	assert.Equal(t, "local_quorum", ssConfig.HistoricalOffloadScyllaConsistency)
+	assert.Equal(t, 1500, ssConfig.HistoricalOffloadScyllaTimeoutMS)
+}
+
+func TestParseSSConfigs_HistoricalFoundationDBFlags(t *testing.T) {
+	appOpts := mapAppOpts{
+		FlagSSEnable:                                                true,
+		FlagHistoricalOffloadFoundationDBEnabled:                    true,
+		FlagHistoricalOffloadFoundationDBClusterFile:                "/etc/foundationdb/fdb.cluster",
+		FlagHistoricalOffloadFoundationDBPrefix:                     "sei_history",
+		FlagHistoricalOffloadFoundationDBAPIVersion:                 730,
+		FlagHistoricalOffloadFoundationDBShards:                     256,
+		FlagHistoricalOffloadFoundationDBTransactionTimeoutMS:       10000,
+		FlagHistoricalOffloadFoundationDBTransactionRetryLimit:      10,
+		FlagHistoricalOffloadFoundationDBTransactionMaxRetryDelayMS: 1000,
+		FlagHistoricalOffloadFoundationDBTransactionSizeLimitBytes:  9000000,
+		FlagSSAsyncWriterBuffer:                                     0,
+	}
+
+	ssConfig := parseSSConfigs(appOpts)
+	assert.True(t, ssConfig.Enable)
+	assert.True(t, ssConfig.HistoricalOffloadFoundationDBEnabled)
+	assert.Equal(t, "/etc/foundationdb/fdb.cluster", ssConfig.HistoricalOffloadFoundationDBClusterFile)
+	assert.Equal(t, "sei_history", ssConfig.HistoricalOffloadFoundationDBPrefix)
+	assert.Equal(t, 730, ssConfig.HistoricalOffloadFoundationDBAPIVersion)
+	assert.Equal(t, 256, ssConfig.HistoricalOffloadFoundationDBShards)
+	assert.Equal(t, 10000, ssConfig.HistoricalOffloadFoundationDBTransactionTimeoutMS)
+	assert.Equal(t, 10, ssConfig.HistoricalOffloadFoundationDBTransactionRetryLimit)
+	assert.Equal(t, 1000, ssConfig.HistoricalOffloadFoundationDBTransactionMaxRetryDelayMS)
+	assert.Equal(t, 9000000, ssConfig.HistoricalOffloadFoundationDBTransactionSizeLimitBytes)
+}
+
 func TestParseReceiptConfigs_DefaultsToPebbleWhenUnset(t *testing.T) {
 	receiptConfig, err := config.ReadReceiptConfig(mapAppOpts{})
 	assert.NoError(t, err)

go.mod

@@ -29,6 +29,7 @@ require (
 	github.com/fortytw2/leaktest v1.3.0
 	github.com/go-git/go-git/v5 v5.17.2
 	github.com/go-kit/kit v0.13.0
+	github.com/gocql/gocql v1.7.0
 	github.com/gofrs/flock v0.13.0
 	github.com/gogo/gateway v1.1.0
 	github.com/gogo/protobuf v1.3.3
@@ -114,11 +115,13 @@ require (
 require (
 	dario.cat/mergo v1.0.0 // indirect
 	github.com/ProtonMail/go-crypto v1.1.6 // indirect
+	github.com/apple/foundationdb/bindings/go v0.0.0-20250406041109-d0457fc011e2 // indirect
 	github.com/cloudflare/circl v1.6.3 // indirect
 	github.com/cyphar/filepath-securejoin v0.4.1 // indirect
 	github.com/emirpasic/gods v1.18.1 // indirect
 	github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 // indirect
 	github.com/go-git/go-billy/v5 v5.8.0 // indirect
+	github.com/hailocab/go-hostpool v0.0.0-20160125115350-e80d13ce29ed // indirect
 	github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 // indirect
 	github.com/kevinburke/ssh_config v1.2.0 // indirect
 	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
@@ -128,6 +131,7 @@ require (
 	github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3 // indirect
 	github.com/skeema/knownhosts v1.3.1 // indirect
 	github.com/xanzy/ssh-agent v0.3.3 // indirect
+	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/warnings.v0 v0.1.2 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -698,6 +698,8 @@ github.com/apache/thrift v0.13.0/go.mod h1:cp2SuWMxlEZw2r+iP2GNCdIi4C1qmUzdZFSVb
 github.com/apache/thrift v0.16.0/go.mod h1:PHK3hniurgQaNMZYaCLEqXKsYK8upmhPbmdP2FXSqgU=
 github.com/apache/thrift v0.22.0 h1:r7mTJdj51TMDe6RtcmNdQxgn9XcyfGDOzegMDRg47uc=
 github.com/apache/thrift v0.22.0/go.mod h1:1e7J/O1Ae6ZQMTYdy9xa3w9k+XHWPfRvdPyJeynQ+/g=
+github.com/apple/foundationdb/bindings/go v0.0.0-20250406041109-d0457fc011e2 h1:N0zyQFUQZEsszDJRukH2mAzv3zWfpTSCsz/iIHmrqWE=
+github.com/apple/foundationdb/bindings/go v0.0.0-20250406041109-d0457fc011e2/go.mod h1:OMVSB21p9+xQUIqlGizHPZfjK+SHws1ht+ZytVDoz9U=
 github.com/armon/circbuf v0.0.0-20150827004946-bbbad097214e/go.mod h1:3U/XgcO3hCbHZ8TKRvWD2dDTCfh9M9ya+I9JpbB7O8o=
 github.com/armon/consul-api v0.0.0-20180202201655-eb2c6b5be1b6/go.mod h1:grANhF5doyWs3UAsr3K4I6qtAmlQcZDesFNEHPZAzj8=
 github.com/armon/go-metrics v0.0.0-20180917152333-f0300d1749da/go.mod h1:Q73ZrmVTwzkszR9V5SSuryQ31EELlFMUz1kKyl939pY=
@@ -736,13 +738,15 @@ github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6r
 github.com/bgentry/speakeasy v0.1.0/go.mod h1:+zsyZBPWlz7T6j88CTgSN5bM796AkVf0kBD4zp0CCIs=
 github.com/bgentry/speakeasy v0.2.0 h1:tgObeVOf8WAvtuAX6DhJ4xks4CFNwPDZiqzGqIHE51E=
 github.com/bgentry/speakeasy v0.2.0/go.mod h1:+zsyZBPWlz7T6j88CTgSN5bM796AkVf0kBD4zp0CCIs=
+github.com/bitly/go-hostpool v0.0.0-20171023180738-a3a6125de932/go.mod h1:NOuUCSz6Q9T7+igc/hlvDOUdtWKryOrtFyIVABv/p7k=
 github.com/bits-and-blooms/bitset v1.7.0/go.mod h1:gIdJ4wp64HaoK2YrL1Q5/N7Y16edYb8uY+O0FJTyyDA=
 github.com/bits-and-blooms/bitset v1.14.2/go.mod h1:7hO7Gc7Pp1vODcmWvKMRA9BNmbv6a/7QIWpPxHddWR8=
 github.com/bits-and-blooms/bitset v1.17.0/go.mod h1:7hO7Gc7Pp1vODcmWvKMRA9BNmbv6a/7QIWpPxHddWR8=
 github.com/bits-and-blooms/bitset v1.24.3 h1:Bte86SlO3lwPQqww+7BE9ZuUCKIjfqnG5jtEyqA9y9Y=
 github.com/bits-and-blooms/bitset v1.24.3/go.mod h1:7hO7Gc7Pp1vODcmWvKMRA9BNmbv6a/7QIWpPxHddWR8=
 github.com/bketelsen/crypt v0.0.4/go.mod h1:aI6NrJ0pMGgvZKL1iVgXLnfIFJtfV+bKCoqOes/6LfM=
 github.com/blang/semver/v4 v4.0.0/go.mod h1:IbckMUScFkM3pff0VJDNKRiT6TG/YpiHIM2yvyW5YoQ=
+github.com/bmizerany/assert v0.0.0-20160611221934-b7ed37b82869/go.mod h1:Ekp36dRnpXw/yCqJaO+ZrUyxD+3VXMFFr56k5XYrpB4=
 github.com/boombuler/barcode v1.0.0/go.mod h1:paBWMcWSl3LHKBqUq+rly7CNSldXjb2rDl3JlRe0mD8=
 github.com/boombuler/barcode v1.0.1/go.mod h1:paBWMcWSl3LHKBqUq+rly7CNSldXjb2rDl3JlRe0mD8=
 github.com/btcsuite/btcd v0.23.2 h1:/YOgUp25sdCnP5ho6Hl3s0E438zlX+Kak7E6TgBgoT0=
@@ -1122,6 +1126,8 @@ github.com/goccy/go-json v0.9.11/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MG
 github.com/goccy/go-json v0.10.4/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
 github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/gocql/gocql v1.7.0 h1:O+7U7/1gSN7QTEAaMEsJc1Oq2QHXvCWoF3DFK9HDHus=
+github.com/gocql/gocql v1.7.0/go.mod h1:vnlvXyFZeLBF0Wy+RS8hrOdbn0UWsWtdg07XJnFxZ+4=
 github.com/godbus/dbus v0.0.0-20190726142602-4481cbc300e2 h1:ZpnhV/YsD2/4cESfV5+Hoeu/iUR3ruzNvZ+yQfO03a0=
 github.com/godbus/dbus v0.0.0-20190726142602-4481cbc300e2/go.mod h1:bBOAhwG1umN6/6ZUMtDFBMQR8jRg9O75tm9K00oMsK4=
 github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
@@ -1328,6 +1334,8 @@ github.com/grpc-ecosystem/grpc-gateway/v2 v2.11.3/go.mod h1:o//XUCC/F+yRGJoPO/VU
 github.com/gsterjov/go-libsecret v0.0.0-20161001094733-a6f4afe4910c h1:6rhixN/i8ZofjG1Y75iExal34USq5p+wiN1tpie8IrU=
 github.com/gsterjov/go-libsecret v0.0.0-20161001094733-a6f4afe4910c/go.mod h1:NMPJylDgVpX0MLRlPy15sqSwOFv/U1GZ2m21JhFfek0=
 github.com/guptarohit/asciigraph v0.5.5/go.mod h1:dYl5wwK4gNsnFf9Zp+l06rFiDZ5YtXM6x7SRWZ3KGag=
+github.com/hailocab/go-hostpool v0.0.0-20160125115350-e80d13ce29ed h1:5upAirOpQc1Q53c0bnx2ufif5kANL7bfZWcc6VJWJd8=
+github.com/hailocab/go-hostpool v0.0.0-20160125115350-e80d13ce29ed/go.mod h1:tMWxXQ9wFIaZeTI9F+hmhFiGpFmhOHzyShyFUhRm0H4=
 github.com/hashicorp/consul/api v1.1.0/go.mod h1:VmuI/Lkw1nC05EYQWNKwWGbkg+FbDBtguAZLlVdkD9Q=
 github.com/hashicorp/consul/api v1.3.0/go.mod h1:MmDNSzIMUjNpY/mQ398R4bk2FnqQLoPndWW5VkKPlCE=
 github.com/hashicorp/consul/sdk v0.1.1/go.mod h1:VKf9jXwCTEY1QZP2MOLRhb5i/I/ssyNV1vwHyQBF0x8=
@@ -2911,6 +2919,8 @@ gopkg.in/cheggaaa/pb.v1 v1.0.25/go.mod h1:V/YB90LKu/1FcN3WVnfiiE5oMCibMjukxqG/qS
 gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=
 gopkg.in/fsnotify.v1 v1.4.7/go.mod h1:Tz8NjZHkW78fSQdbUxIjBTcgA1z1m8ZHf0WmKUhAMys=
 gopkg.in/gcfg.v1 v1.2.3/go.mod h1:yesOnuUOFQAhST5vPY4nbZsb/huCgGGXlipJsBn0b3o=
+gopkg.in/inf.v0 v0.9.1 h1:73M5CoZyi3ZLMOyDlQh031Cx6N9NDJ2Vvfl76EDAgDc=
+gopkg.in/inf.v0 v0.9.1/go.mod h1:cWUDdTG/fYaXco+Dcufb5Vnc6Gp2YChqWtbxRZE0mXw=
 gopkg.in/ini.v1 v1.62.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
 gopkg.in/ini.v1 v1.67.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
 gopkg.in/natefinch/lumberjack.v2 v2.2.1 h1:bBRl1b0OH9s/DuPhuXpNl+VtCaJXFZ5/uEFST95x9zc=

sei-db/config/ss_config.go

@@ -76,6 +76,56 @@ type StateStoreConfig struct {
 	// When true, data is routed to separate DBs by EVM key family while
 	// preserving the same logical store key and full key encoding inside each DB.
 	SeparateEVMSubDBs bool `mapstructure:"evm-separate-dbs"`
+
+	// HistoricalOffloadScyllaHosts enables ScyllaDB/Cassandra fallback reads
+	// for versions pruned from local SS when non-empty. Hosts are comma-separated
+	// host[:port] values.
+	HistoricalOffloadScyllaHosts string `mapstructure:"historical-offload-scylla-hosts"`
+
+	// HistoricalOffloadScyllaKeyspace is the keyspace containing state_mutations.
+	HistoricalOffloadScyllaKeyspace string `mapstructure:"historical-offload-scylla-keyspace"`
+
+	// HistoricalOffloadScyllaUsername and Password are optional.
+	HistoricalOffloadScyllaUsername string `mapstructure:"historical-offload-scylla-username"`
+	HistoricalOffloadScyllaPassword string `mapstructure:"historical-offload-scylla-password"`
+
+	// HistoricalOffloadScyllaDatacenter enables DC-aware routing when set.
+	HistoricalOffloadScyllaDatacenter string `mapstructure:"historical-offload-scylla-datacenter"`
+
+	// HistoricalOffloadScyllaConsistency defaults to local_quorum when empty.
+	HistoricalOffloadScyllaConsistency string `mapstructure:"historical-offload-scylla-consistency"`
+
+	// HistoricalOffloadScyllaTimeoutMS defaults in the Scylla reader when zero.
+	HistoricalOffloadScyllaTimeoutMS int `mapstructure:"historical-offload-scylla-timeout-ms"`
+
+	// HistoricalOffloadFoundationDBEnabled enables FoundationDB fallback reads
+	// for versions pruned from local SS.
+	HistoricalOffloadFoundationDBEnabled bool `mapstructure:"historical-offload-foundationdb-enabled"`
+
+	// HistoricalOffloadFoundationDBClusterFile is optional; empty uses the
+	// FoundationDB client library's default cluster file.
+	HistoricalOffloadFoundationDBClusterFile string `mapstructure:"historical-offload-foundationdb-cluster-file"`
+
+	// HistoricalOffloadFoundationDBPrefix isolates this chain's keys in FDB.
+	HistoricalOffloadFoundationDBPrefix string `mapstructure:"historical-offload-foundationdb-prefix"`
+
+	// HistoricalOffloadFoundationDBAPIVersion defaults in the FDB reader when zero.
+	HistoricalOffloadFoundationDBAPIVersion int `mapstructure:"historical-offload-foundationdb-api-version"`
+
+	// HistoricalOffloadFoundationDBShards defaults in the FDB reader when zero.
+	HistoricalOffloadFoundationDBShards int `mapstructure:"historical-offload-foundationdb-shards"`
+
+	// HistoricalOffloadFoundationDBTransactionTimeoutMS bounds each FDB transaction.
+	HistoricalOffloadFoundationDBTransactionTimeoutMS int `mapstructure:"historical-offload-foundationdb-transaction-timeout-ms"`
+
+	// HistoricalOffloadFoundationDBTransactionRetryLimit bounds FDB retry loops.
+	HistoricalOffloadFoundationDBTransactionRetryLimit int `mapstructure:"historical-offload-foundationdb-transaction-retry-limit"`
+
+	// HistoricalOffloadFoundationDBTransactionMaxRetryDelayMS bounds FDB retry backoff.
+	HistoricalOffloadFoundationDBTransactionMaxRetryDelayMS int `mapstructure:"historical-offload-foundationdb-transaction-max-retry-delay-ms"`
+
+	// HistoricalOffloadFoundationDBTransactionSizeLimitBytes bounds FDB transaction size.
+	HistoricalOffloadFoundationDBTransactionSizeLimitBytes int `mapstructure:"historical-offload-foundationdb-transaction-size-limit-bytes"`
 }
 
 // DefaultStateStoreConfig returns the default StateStoreConfig