forks/go-ethereum
1
0
Fork 1
mirror of https://github.com/ethereum/go-ethereum.git synced 2026-06-08 07:58:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

cmd, eth: improve partial state flag documentation and categorization

Browse source 
Move partial state CLI flags into their own "PARTIAL STATE" help category
(matching BEACON CHAIN, DEVELOPER CHAIN patterns), improve Usage strings
with examples and constraint descriptions, expand PartialStateConfig doc
comments to explain EIP-7928 implications, and raise BAL retention minimum
from 64 to 256 (required by BLOCKHASH opcode).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
CPerezz 2026-02-17 10:49:21 +01:00
parent cdb4d77819
commit e59c92959c
No known key found for this signature in database
GPG key ID: 62045F34B97177DD
4 changed files with 55 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
cmd/utils/flags.go
View file

@ -315,33 +315,33 @@ var (
Value: uint(ethconfig.Defaults.NodeFullValueCheckpoint),
Category: flags.StateCategory,
}
// Partial statefulness flags
// Partial state flags (EIP-7928 BAL-based partial statefulness)
PartialStateFlag = &cli.BoolFlag{
Name: "partial-state",
Usage: "Enable partial statefulness mode (reduced storage, requires BAL support)",
Category: flags.StateCategory,
Usage: "Enable partial state mode: sync all accounts but only storage for tracked contracts (requires EIP-7928 BAL)",
Category: flags.PartialStateCategory,
}
PartialStateContractsFlag = &cli.StringSliceFlag{
Name: "partial-state.contracts",
Usage: "Contracts to track storage for in partial state mode (comma-separated addresses)",
Category: flags.StateCategory,
Usage: "Contract addresses to track full storage for (comma-separated hex, e.g. 0xC02a...,0xA0b8...)",
Category: flags.PartialStateCategory,
}
PartialStateContractsFileFlag = &cli.StringFlag{
Name: "partial-state.contracts-file",
Usage: "JSON file containing contracts to track in partial state mode",
Category: flags.StateCategory,
Usage: `Path to JSON file listing contracts to track (format: {"version":1,"contracts":[{"address":"0x..."}]})`,
Category: flags.PartialStateCategory,
}
PartialStateBALRetentionFlag = &cli.Uint64Flag{
Name: "partial-state.bal-retention",
Usage: "Number of blocks to retain BAL history for reorg handling",
Usage: "Number of blocks to retain BAL history for reorg handling (minimum 256 for BLOCKHASH)",
Value: ethconfig.Defaults.PartialState.BALRetention,
Category: flags.StateCategory,
Category: flags.PartialStateCategory,
}
PartialStateChainRetentionFlag = &cli.Uint64Flag{
Name: "partial-state.chain-retention",
Usage: "Number of recent blocks to retain bodies and receipts for (0 = keep all)",
Usage: "Number of recent blocks to retain bodies and receipts for (default = ~3.4 hours, 0 = keep all)",
Value: ethconfig.DefaultChainRetention,
Category: flags.StateCategory,
Category: flags.PartialStateCategory,
}
TransactionHistoryFlag = &cli.Uint64Flag{
Name: "history.transactions",

5
eth/backend.go
View file

@ -355,7 +355,10 @@ func New(stack *node.Node, config *ethconfig.Config) (*Ethereum, error) {
return nil, fmt.Errorf("failed to load partial state contracts: %w", err)
}
partialFilter = partial.NewConfiguredFilter(config.PartialState.Contracts)
log.Info("Partial statefulness enabled", "contracts", len(config.PartialState.Contracts))
log.Info("Partial state mode enabled",
"contracts", len(config.PartialState.Contracts),
"balRetention", config.PartialState.BALRetention,
"chainRetention", config.PartialState.ChainRetention)
}
if eth.handler, err = newHandler(&handlerConfig{

30
eth/ethconfig/config.go
View file

@ -229,27 +229,39 @@ type Config struct {
// --partial-state.chain-retention.
const DefaultChainRetention = 1024
// PartialStateConfig configures partial statefulness mode.
// When enabled, the node stores all accounts but only storage for configured contracts.
// State updates are applied via Block Access Lists (BALs) per EIP-7928.
// PartialStateConfig configures partial statefulness mode (EIP-7928).
//
// When enabled, the node maintains the full account trie (all accounts, balances,
// nonces, code hashes) but only stores storage for explicitly tracked contracts.
// Blocks are processed using Block Access Lists (BALs) instead of re-executing
// transactions, dramatically reducing both storage requirements and CPU usage.
//
// Requires a network that supports EIP-7928 BAL propagation via the Engine API.
type PartialStateConfig struct {
// Enabled activates partial statefulness mode
// Enabled activates partial state mode. When true, snap sync downloads
// all accounts but skips storage and bytecode for untracked contracts.
Enabled bool
// Contracts is the list of contracts to track storage for
// Contracts is the list of contract addresses to track full storage for.
// Storage for contracts not in this list is skipped during sync, so
// eth_getStorageAt returns zero values and eth_call may produce incorrect
// results when touching untracked contracts.
Contracts []common.Address
// ContractsFile is the path to a JSON file containing contract addresses
// to track. Merged with Contracts above. See loadContractsFromFile for format.
ContractsFile string `toml:",omitempty"`
// BALRetention is the number of blocks to keep BAL history for reorg handling
// BALRetention is the number of blocks to keep BAL history for. Must
// be at least 256 (BLOCKHASH opcode requires 256 blocks of history).
// Increase beyond 256 to support deeper reorg windows. Default 256.
BALRetention uint64
// ChainRetention is the number of recent blocks to retain bodies and
// receipts for. Older blocks only keep their headers. During sync, bodies
// and receipts outside this window are never downloaded. After sync, the
// freezer enforces a rolling window, deleting aged-out data. Set to 0 to
// keep all chain history.
// keep all chain history. Default 1024 (~3.4 hours at 12s/block).
ChainRetention uint64
}
@ -339,8 +351,8 @@ func (c *PartialStateConfig) Validate() error {
}
// Validate BAL retention
if c.BALRetention < 64 {
return fmt.Errorf("BAL retention must be at least 64 blocks (for BLOCKHASH support), got %d", c.BALRetention)
if c.BALRetention < 256 {
return fmt.Errorf("BAL retention must be at least 256 blocks (for BLOCKHASH opcode support), got %d", c.BALRetention)
}
return nil

37
internal/flags/categories.go
View file

@ -19,24 +19,25 @@ package flags
import "github.com/urfave/cli/v2"
const (
EthCategory = "ETHEREUM"
BeaconCategory = "BEACON CHAIN"
DevCategory = "DEVELOPER CHAIN"
StateCategory = "STATE HISTORY MANAGEMENT"
TxPoolCategory = "TRANSACTION POOL (EVM)"
BlobPoolCategory = "TRANSACTION POOL (BLOB)"
PerfCategory = "PERFORMANCE TUNING"
AccountCategory = "ACCOUNT"
APICategory = "API AND CONSOLE"
NetworkingCategory = "NETWORKING"
MinerCategory = "MINER"
GasPriceCategory = "GAS PRICE ORACLE"
VMCategory = "VIRTUAL MACHINE"
LoggingCategory = "LOGGING AND DEBUGGING"
MetricsCategory = "METRICS AND STATS"
MiscCategory = "MISC"
TestingCategory = "TESTING"
DeprecatedCategory = "ALIASED (deprecated)"
EthCategory = "ETHEREUM"
BeaconCategory = "BEACON CHAIN"
DevCategory = "DEVELOPER CHAIN"
StateCategory = "STATE HISTORY MANAGEMENT"
PartialStateCategory = "PARTIAL STATE"
TxPoolCategory = "TRANSACTION POOL (EVM)"
BlobPoolCategory = "TRANSACTION POOL (BLOB)"
PerfCategory = "PERFORMANCE TUNING"
AccountCategory = "ACCOUNT"
APICategory = "API AND CONSOLE"
NetworkingCategory = "NETWORKING"
MinerCategory = "MINER"
GasPriceCategory = "GAS PRICE ORACLE"
VMCategory = "VIRTUAL MACHINE"
LoggingCategory = "LOGGING AND DEBUGGING"
MetricsCategory = "METRICS AND STATS"
MiscCategory = "MISC"
TestingCategory = "TESTING"
DeprecatedCategory = "ALIASED (deprecated)"
)
func init() {