added rate limiting to address biased trie cache preloading (#2029)

* added rate limiting to address biased trie cache preloading

* updated default limit to 512KB/sec and a small update in limiter

* added unit tests

* updated default to 1MB/s and updated comments

* reduced code duplication

* triedb/pathdb: skip the node in preloading if it's size is > burst size

Author: pratikspatil024

core/blockchain.go

@@ -198,6 +198,11 @@ type BlockChainConfig struct {
 	// Maps account address to cache size in bytes
 	AddressCacheSizes map[common.Address]int
 
+	// PreloadRateLimit limits cache preload I/O in bytes per second per address.
+	// This prevents preloading from overwhelming the disk during sync.
+	// 0 = unlimited (legacy behavior), default = 1MB/s
+	PreloadRateLimit int64
+
 	// State snapshot related options
 	SnapshotLimit   int  // Memory allowance (MB) to use for caching snapshot entries in memory
 	SnapshotNoBuild bool // Whether the background generation is allowed
@@ -302,6 +307,7 @@ func (cfg *BlockChainConfig) triedbConfig(isVerkle bool) *triedb.Config {
 			WriteBufferSize:   cfg.TrieDirtyLimit * 1024 * 1024,
 			NoAsyncFlush:      cfg.TrieNoAsyncFlush,
 			AddressCacheSizes: cfg.AddressCacheSizes,
+			PreloadRateLimit:  cfg.PreloadRateLimit,
 		}
 	}
 	return config

eth/backend.go

@@ -278,6 +278,7 @@ func New(stack *node.Node, config *ethconfig.Config) (*Ethereum, error) {
 			ChainHistoryMode:  config.HistoryMode,
 			TxLookupLimit:     int64(min(config.TransactionHistory, math.MaxInt64)),
 			AddressCacheSizes: config.AddressCacheSizes,
+			PreloadRateLimit:  config.PreloadRateLimit,
 			VmConfig: vm.Config{
 				EnablePreimageRecording: config.EnablePreimageRecording,
 				EnableWitnessStats:      config.EnableWitnessStats,

eth/ethconfig/config.go

@@ -162,6 +162,11 @@ type Config struct {
 	// Maps account address to cache size in bytes
 	AddressCacheSizes map[common.Address]int
 
+	// PreloadRateLimit limits cache preload I/O in bytes per second per address.
+	// This prevents preloading from overwhelming the disk during sync.
+	// 0 = unlimited (legacy behavior), default = 1MB/s
+	PreloadRateLimit int64
+
 	// Mining options
 	Miner miner.Config
 

internal/cli/server/config.go

@@ -679,6 +679,11 @@ type CacheConfig struct {
 	AddressCacheSizesRaw string            `hcl:"addresscachesizes,optional" toml:"addresscachesizes,optional"`
 	AddressCacheSizes    map[string]string `hcl:"-,optional" toml:"-"`
 
+	// PreloadRateLimit limits cache preload I/O in bytes per second per address.
+	// This prevents preloading from overwhelming the disk during sync.
+	// Accepts values like "500KB", "1MB", "0" (for unlimited). Default: 1MB/s
+	PreloadRateLimit string `hcl:"preloadratelimit,optional" toml:"preloadratelimit,optional"`
+
 	// GC settings
 	// GoMemLimit sets the soft memory limit for the runtime
 	GoMemLimit string `hcl:"gomemlimit,optional" toml:"gomemlimit,optional"`
@@ -1436,6 +1441,20 @@ func (c *Config) buildEth(stack *node.Node, accountManager *accounts.Manager) (*
 				n.AddressCacheSizes = addressCacheSizes
 			}
 		}
+
+		// Parse preload rate limit (default: 1MB/s per address)
+		if c.Cache.PreloadRateLimit != "" {
+			rateLimitBytes, err := parseByteSize(c.Cache.PreloadRateLimit)
+			if err != nil {
+				log.Warn("Failed to parse preload rate limit, using default 1MB/s per address", "error", err)
+				n.PreloadRateLimit = 1024 * 1024
+			} else {
+				n.PreloadRateLimit = rateLimitBytes
+			}
+		} else {
+			// Default to 1MB/s per address if not specified
+			n.PreloadRateLimit = 1024 * 1024
+		}
 	}
 
 	// History
@@ -1598,6 +1617,46 @@ func parseAddressCacheSizes(input string) (map[common.Address]int, error) {
 	return result, nil
 }
 
+// parseByteSize parses a byte size string like "5MB", "10MB", "1GB", or "0" (for unlimited)
+// Returns the size in bytes. Supported suffixes: B, KB, MB, GB (case insensitive)
+func parseByteSize(input string) (int64, error) {
+	input = strings.TrimSpace(input)
+	if input == "" || input == "0" {
+		return 0, nil
+	}
+
+	input = strings.ToUpper(input)
+
+	var multiplier int64 = 1
+	var numStr string
+
+	switch {
+	case strings.HasSuffix(input, "GB"):
+		multiplier = 1024 * 1024 * 1024
+		numStr = strings.TrimSuffix(input, "GB")
+	case strings.HasSuffix(input, "MB"):
+		multiplier = 1024 * 1024
+		numStr = strings.TrimSuffix(input, "MB")
+	case strings.HasSuffix(input, "KB"):
+		multiplier = 1024
+		numStr = strings.TrimSuffix(input, "KB")
+	case strings.HasSuffix(input, "B"):
+		multiplier = 1
+		numStr = strings.TrimSuffix(input, "B")
+	default:
+		// Assume bytes if no suffix
+		numStr = input
+	}
+
+	numStr = strings.TrimSpace(numStr)
+	num, err := strconv.ParseInt(numStr, 10, 64)
+	if err != nil {
+		return 0, fmt.Errorf("invalid byte size: %s", input)
+	}
+
+	return num * multiplier, nil
+}
+
 var (
 	clientIdentifier = "bor"
 	gitCommit        = "" // Git SHA1 commit hash of the release (set via linker flags)

internal/cli/server/config_test.go

@@ -292,6 +292,93 @@ func TestSealerBothGasParametersConfig(t *testing.T) {
 	})
 }
 
+// TestParseByteSize tests the parseByteSize helper function for parsing
+// human-readable byte size strings (e.g., "500KB", "5MB", "1GB").
+func TestParseByteSize(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected int64
+		wantErr  bool
+	}{
+		// Valid inputs with different suffixes
+		{"bytes", "1024B", 1024, false},
+		{"kilobytes", "500KB", 500 * 1024, false},
+		{"megabytes", "5MB", 5 * 1024 * 1024, false},
+		{"gigabytes", "1GB", 1 * 1024 * 1024 * 1024, false},
+
+		// Case insensitivity
+		{"lowercase kb", "500kb", 500 * 1024, false},
+		{"lowercase mb", "5mb", 5 * 1024 * 1024, false},
+		{"mixed case", "5Mb", 5 * 1024 * 1024, false},
+
+		// No suffix (assumes bytes)
+		{"no suffix", "1024", 1024, false},
+
+		// Zero and empty
+		{"zero string", "0", 0, false},
+		{"empty string", "", 0, false},
+
+		// Whitespace handling
+		{"leading space", "  500KB", 500 * 1024, false},
+		{"trailing space", "500KB  ", 500 * 1024, false},
+		{"space before suffix", "500 KB", 500 * 1024, false},
+
+		// Invalid inputs
+		{"invalid suffix", "500XB", 0, true},
+		{"non-numeric", "abcMB", 0, true},
+		{"float", "5.5MB", 0, true},
+
+		// Note: negative values are technically parsed by ParseInt,
+		// but produce negative results which are invalid for byte sizes.
+		// The calling code should validate the result is non-negative.
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result, err := parseByteSize(tt.input)
+			if tt.wantErr {
+				assert.Error(t, err, "expected error for input: %s", tt.input)
+			} else {
+				assert.NoError(t, err, "unexpected error for input: %s", tt.input)
+				assert.Equal(t, tt.expected, result, "unexpected result for input: %s", tt.input)
+			}
+		})
+	}
+}
+
+// TestPreloadRateLimitConfig tests the preload rate limit configuration parsing.
+func TestPreloadRateLimitConfig(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected int64
+	}{
+		{"empty string defaults to 1MB/s", "", 1024 * 1024},
+		{"explicit 1MB", "1MB", 1024 * 1024},
+		{"unlimited (0)", "0", 0},
+		{"invalid falls back to 1MB/s", "invalid", 1024 * 1024},
+		{"500KB", "500KB", 500 * 1024},
+		{"2MB", "2MB", 2 * 1024 * 1024},
+		{"lowercase 100kb", "100kb", 100 * 1024},
+		{"lowercase 10mb", "10mb", 10 * 1024 * 1024},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			config := DefaultConfig()
+			config.Cache.PreloadRateLimit = tt.input
+
+			assert.NoError(t, config.loadChain())
+
+			ethConfig, err := config.buildEth(nil, nil)
+			assert.NoError(t, err)
+
+			assert.Equal(t, tt.expected, ethConfig.PreloadRateLimit, "input: %s", tt.input)
+		})
+	}
+}
+
 // TestDeveloperModeGasParameters tests the developer mode specific code path
 // for setting TargetGasPercentage and BaseFeeChangeDenominator (lines 1293-1304 in config.go).
 // The default config uses mainnet which has Bor config, so these tests actually execute lines 1293-1304.

internal/cli/server/flags.go

@@ -559,6 +559,13 @@ func (c *Command) Flags(config *Config) *flagset.Flagset {
 		Default: c.cliConfig.Cache.AddressCacheSizesRaw,
 		Group:   "Cache",
 	})
+	f.StringFlag(&flagset.StringFlag{
+		Name:    "cache.preloadratelimit",
+		Usage:   "Rate limit per address for cache preloading (e.g. 500KB, 1MB, 0 for unlimited). Limits I/O during sync. Default: 1MB",
+		Value:   &c.cliConfig.Cache.PreloadRateLimit,
+		Default: c.cliConfig.Cache.PreloadRateLimit,
+		Group:   "Cache",
+	})
 	f.Uint64Flag(&flagset.Uint64Flag{
 		Name:    "cache.triesinmemory",
 		Usage:   "Number of block states (tries) to keep in memory",

triedb/pathdb/biased_fastcache.go

@@ -13,6 +13,7 @@ import (
 	"github.com/ethereum/go-ethereum/ethdb"
 	"github.com/ethereum/go-ethereum/log"
 	"github.com/ethereum/go-ethereum/metrics"
+	"golang.org/x/time/rate"
 )
 
 var (
@@ -44,20 +45,25 @@ type AddressBiasedCache struct {
 	ctx    stdcontext.Context
 	cancel stdcontext.CancelFunc
 	wg     sync.WaitGroup // Wait for all preloads to finish
+
+	// Rate limiting for preload operations (bytes per second, 0 = unlimited)
+	rateLimitBPS int64
 }
 
 // NewAddressBiasedCache creates a new address-biased cache with preloading.
 // It scans the database for storage trie nodes of the specified addresses and
 // loads them into dedicated caches. The addressCacheSizes maps each address to
 // its desired cache size in bytes. The commonCacheSize specifies the size
-// of the cache for non-preloaded data.
+// of the cache for non-preloaded data. The rateLimitBPS limits preload I/O
+// in bytes per second (0 = unlimited).
 // Preloading happens asynchronously in the background.
-func NewAddressBiasedCache(db ethdb.Database, addressCacheSizes map[common.Address]int, commonCacheSize int) (*AddressBiasedCache, error) {
+func NewAddressBiasedCache(db ethdb.Database, addressCacheSizes map[common.Address]int, commonCacheSize int, rateLimitBPS int64) (*AddressBiasedCache, error) {
 	ctx, cancel := stdcontext.WithCancel(stdcontext.Background())
 	cache := &AddressBiasedCache{
-		commonCache: fastcache.New(commonCacheSize),
-		ctx:         ctx,
-		cancel:      cancel,
+		commonCache:  fastcache.New(commonCacheSize),
+		ctx:          ctx,
+		cancel:       cancel,
+		rateLimitBPS: rateLimitBPS,
 	}
 
 	// Initialize caches synchronously, but preload asynchronously
@@ -86,6 +92,7 @@ func (c *AddressBiasedCache) initAddressCache(addr common.Address, cacheSize int
 // BFS traversal, prioritizing shallow nodes (most frequently accessed) until
 // the cache is full. This naturally loads nodes by depth, filling the cache
 // with as many upper-level nodes as possible. This function runs asynchronously.
+// Rate limiting is applied to prevent overwhelming the disk during sync.
 func (c *AddressBiasedCache) preloadAddressAsync(db ethdb.Database, addr common.Address, cacheSize int) {
 	defer c.wg.Done()
 	startTime := time.Now()
@@ -100,14 +107,25 @@ func (c *AddressBiasedCache) preloadAddressAsync(db ethdb.Database, addr common.
 	}
 	addrCache := cacheValue.(*fastcache.Cache)
 
+	// Create rate limiter if configured (burst of 64KB for smoother throttling)
+	var limiter *rate.Limiter
+	if c.rateLimitBPS > 0 {
+		limiter = rate.NewLimiter(rate.Limit(c.rateLimitBPS), 64*1024)
+	}
+
 	// Local stats for logging progress
 	var entriesLoaded int
 	var totalBytesLoaded uint64
 
+	rateLimitStr := "unlimited"
+	if c.rateLimitBPS > 0 {
+		rateLimitStr = fmt.Sprintf("%s/s", common.StorageSize(c.rateLimitBPS))
+	}
 	log.Info("Starting storage trie preload",
 		"address", addr.Hex(),
 		"account hash", accountHash.Hex(),
-		"cache size", common.StorageSize(cacheSize).String())
+		"cache size", common.StorageSize(cacheSize).String(),
+		"rate limit", rateLimitStr)
 
 	var maxDepthReached int
 	const logInterval = 100000
@@ -156,6 +174,27 @@ func (c *AddressBiasedCache) preloadAddressAsync(db ethdb.Database, addr common.
 			continue
 		}
 
+		// Apply rate limiting after reading, based on actual bytes read
+		if limiter != nil {
+			if err := limiter.WaitN(c.ctx, len(nodeData)); err != nil {
+				if c.ctx.Err() != nil {
+					log.Info("Preload interrupted during shutdown",
+						"account hash", accountHash.Hex(),
+						"entries", entriesLoaded,
+						"max depth", maxDepthReached,
+						"size", common.StorageSize(totalBytesLoaded).String(),
+						"elapsed", time.Since(startTime))
+					return
+				}
+				// Node exceeds burst size — skip it and continue preloading
+				log.Warn("Preload skipping oversized node",
+					"account hash", accountHash.Hex(),
+					"node size", len(nodeData),
+					"burst", limiter.Burst())
+				continue
+			}
+		}
+
 		// Check if adding this node would exceed cache size
 		// Key format: owner (32 bytes) + path
 		nodeSize := uint64(common.HashLength + len(item.path) + len(nodeData))