features

README

Prysm Feature Flags

Part of Prysm's feature development often involves use of feature flags which serve as a way to toggle new features as they are introduced. Using this methodology, you are assured that your feature can be safely tested in production with a fall back option if any regression were to occur. This reduces the likelihood of an emergency release or rollback of a given feature due to unforeseen issues.

When to use a feature flag?

It is best to use a feature flag any time you are adding or removing functionality in an existing critical application path.

Examples of when to use a feature flag:

• Adding a caching layer to an expensive RPC call.
• Optimizing a particular algorithm or routine.
• Introducing a temporary public testnet configuration.

Examples of when not to use a feature flag:

• Adding a new gRPC endpoint. (Unless dangerous or expensive to expose).
• Adding new logging statements.
• Removing dead code.
• Adding any trivial feature with no risk of regressions to existing functionality.

How to use a feature flag?

Once it has been decided that you should use a feature flag. Follow these steps to safely releasing your feature. In general, try to create a single PR for each step of this process.

1. Add your feature flag to shared/featureconfig/flags.go, use the flag to toggle a boolean in the feature config in shared/featureconfig/config.go. It is a good idea to use the enable prefix for your flag since you're going to invert the flag in a later step. i.e you will use disable prefix later. For example, --enable-my-feature. Additionally, create a feature flag tracking issue for your feature using the appropriate issue template.
2. Use the feature throughout the application to enable your new functionality and be sure to write tests carefully and thoughtfully to ensure you have tested all of your new functionality without losing coverage on the existing functionality. This is considered an opt-in feature flag. Example usage:

func someExistingMethod(ctx context.Context) error {
    if features.Get().MyNewFeature {
       return newMethod(ctx)
    }
    // Otherwise continue with the existing code path.
}

1. Add the flag to the end to end tests. This set of flags can also be found in shared/featureconfig/flags.go.
2. Test the functionality locally and safely in production. Once you have enough confidence that your new function works and is safe to release then move onto the next step.
3. Move your existing flag to the deprecated section of shared/featureconfig/flags.go. It is important NOT to delete your existing flag outright. Deleting a flag can be extremely frustrating to users as it may break their existing workflow! Marking a flag as deprecated gives users time to adjust their start scripts and workflow. Add another feature flag to represent the inverse of your flag from step 1. For example --disable-my-feature. Read the value of this flag to appropriately the config value in shared/featureconfig/config.go.
4. After your feature has been included in a release as "opt-out" and there are no issues, deprecate the opt-out feature flag, delete the config field from shared/featureconfig/config.go, delete any deprecated / obsolete code paths.

Deprecated flags are deleted upon each major semver point release. Ex: v1, v2, v3.

Documentation

Overview

Package features defines which features are enabled for runtime in order to selectively enable certain features to maintain a stable runtime.

The process for implementing new features using this package is as follows:

1. Add a new CMD flag in flags.go, and place it in the proper list(s) var for its client.
2. Add a condition for the flag in the proper Configure function(s) below.
3. Place any "new" behavior in the `if flagEnabled` statement.
4. Place any "previous" behavior in the `else` statement.
5. Ensure any tests using the new feature fail if the flag isn't enabled. 5a. Use the following to enable your flag for tests: cfg := &featureconfig.Flags{ VerifyAttestationSigs: true, } resetCfg := featureconfig.InitWithReset(cfg) defer resetCfg()
6. Add the string for the flags that should be running within E2E to E2EValidatorFlags and E2EBeaconChainFlags.

Index

• Variables
• func ActiveFlags(flags []cli.Flag) []cli.Flag
• func ConfigureBeaconChain(ctx *cli.Context) error
• func ConfigureValidator(ctx *cli.Context) error
• func Init(c *Flags)
• func InitWithReset(c *Flags) func()
• type Flags
  • func Get() *Flags

Variables

var (
	// PraterTestnet flag for the multiclient Ethereum consensus testnet.
	PraterTestnet = &cli.BoolFlag{
		Name:    "prater",
		Usage:   "Runs Prysm configured for the Prater / Goerli test network.",
		Aliases: []string{"goerli"},
	}
	// SepoliaTestnet flag for the multiclient Ethereum consensus testnet.
	SepoliaTestnet = &cli.BoolFlag{
		Name:  "sepolia",
		Usage: "Runs Prysm configured for the Sepolia test network.",
	}
	// HoleskyTestnet flag for the multiclient Ethereum consensus testnet.
	HoleskyTestnet = &cli.BoolFlag{
		Name:  "holesky",
		Usage: "Runs Prysm configured for the Holesky test network.",
	}
	// Mainnet flag for easier tooling, no-op
	Mainnet = &cli.BoolFlag{
		Value: true,
		Name:  "mainnet",
		Usage: "Runs on Ethereum main network. This is the default and can be omitted.",
	}

	SaveFullExecutionPayloads = &cli.BoolFlag{
		Name:  "save-full-execution-payloads",
		Usage: "Saves beacon blocks with full execution payloads instead of execution payload headers in the database.",
	}
	EnableBeaconRESTApi = &cli.BoolFlag{
		Name:  "enable-beacon-rest-api",
		Usage: "(Experimental): Enables of the beacon REST API when querying a beacon node.",
	}

	DisableEIP4881 = &cli.BoolFlag{
		Name:  "disable-eip-4881",
		Usage: "Disables the deposit tree specified in EIP-4881.",
	}
	EnableLightClient = &cli.BoolFlag{
		Name:  "enable-lightclient",
		Usage: "Enables the light client support in the beacon node",
	}

	// DisableRegistrationCache a flag for disabling the validator registration cache and use db instead.
	DisableRegistrationCache = &cli.BoolFlag{
		Name:  "disable-registration-cache",
		Usage: "Temporary flag for disabling the validator registration cache instead of using the DB. Note: registrations do not clear on restart while using the DB.",
	}
	// BlobSaveFsync enforces durable filesystem writes for use cases where blob availability is critical.
	BlobSaveFsync = &cli.BoolFlag{
		Name:  "blob-save-fsync",
		Usage: "Forces new blob files to be fysnc'd before continuing, ensuring durable blob writes.",
	}
)

var BeaconChainFlags = append(deprecatedBeaconFlags, append(deprecatedFlags, []cli.Flag{
	devModeFlag,
	enableExperimentalState,
	writeSSZStateTransitionsFlag,
	disableGRPCConnectionLogging,
	HoleskyTestnet,
	PraterTestnet,
	SepoliaTestnet,
	Mainnet,
	disablePeerScorer,
	disableBroadcastSlashingFlag,
	enableSlasherFlag,
	enableHistoricalSpaceRepresentation,
	disableStakinContractCheck,
	SaveFullExecutionPayloads,
	enableStartupOptimistic,
	enableFullSSZDataLogging,
	disableVerboseSigVerification,
	prepareAllPayloads,
	aggregateFirstInterval,
	aggregateSecondInterval,
	aggregateThirdInterval,
	DisableEIP4881,
	disableResourceManager,
	DisableRegistrationCache,
	EnableLightClient,
	BlobSaveFsync,
}...)...)

BeaconChainFlags contains a list of all the feature flags that apply to the beacon-chain client.

var E2EBeaconChainFlags = []string{
	"--dev",
}

E2EBeaconChainFlags contains a list of the beacon chain feature flags to be tested in E2E.

var E2EValidatorFlags = []string{
	"--enable-doppelganger",
}

E2EValidatorFlags contains a list of the validator feature flags to be tested in E2E.

var NetworkFlags = []cli.Flag{
	Mainnet,
	PraterTestnet,
	SepoliaTestnet,
	HoleskyTestnet,
}

NetworkFlags contains a list of network flags.

var ValidatorFlags = append(deprecatedFlags, []cli.Flag{
	writeWalletPasswordOnWebOnboarding,
	HoleskyTestnet,
	PraterTestnet,
	SepoliaTestnet,
	Mainnet,
	dynamicKeyReloadDebounceInterval,
	attestTimely,
	enableSlashingProtectionPruning,
	enableDoppelGangerProtection,
	EnableBeaconRESTApi,
}...)

ValidatorFlags contains a list of all the feature flags that apply to the validator client.

Functions

func ActiveFlags

func ActiveFlags(flags []cli.Flag) []cli.Flag

ActiveFlags returns all of the flags that are not Hidden.

func ConfigureBeaconChain

func ConfigureBeaconChain(ctx *cli.Context) error

ConfigureBeaconChain sets the global config based on what flags are enabled for the beacon-chain client.

func ConfigureValidator

func ConfigureValidator(ctx *cli.Context) error

ConfigureValidator sets the global config based on what flags are enabled for the validator client.

func Init

func Init(c *Flags)

Init sets the global config equal to the config that is passed in.

func InitWithReset

func InitWithReset(c *Flags) func()

InitWithReset sets the global config and returns function that is used to reset configuration.

Types

type Flags

type Flags struct {
	// Feature related flags.
	EnableExperimentalState             bool // EnableExperimentalState turns on the latest and greatest (but potentially unstable) changes to the beacon state.
	WriteSSZStateTransitions            bool // WriteSSZStateTransitions to tmp directory.
	EnablePeerScorer                    bool // EnablePeerScorer enables experimental peer scoring in p2p.
	EnableLightClient                   bool // EnableLightClient enables light client APIs.
	WriteWalletPasswordOnWebOnboarding  bool // WriteWalletPasswordOnWebOnboarding writes the password to disk after Prysm web signup.
	EnableDoppelGanger                  bool // EnableDoppelGanger enables doppelganger protection on startup for the validator.
	EnableHistoricalSpaceRepresentation bool // EnableHistoricalSpaceRepresentation enables the saving of registry validators in separate buckets to save space
	EnableBeaconRESTApi                 bool // EnableBeaconRESTApi enables experimental usage of the beacon REST API by the validator when querying a beacon node
	// Logging related toggles.
	DisableGRPCConnectionLogs bool // Disables logging when a new grpc client has connected.
	EnableFullSSZDataLogging  bool // Enables logging for full ssz data on rejected gossip messages

	// Slasher toggles.
	DisableBroadcastSlashings bool // DisableBroadcastSlashings disables p2p broadcasting of proposer and attester slashings.

	// Bug fixes related flags.
	AttestTimely bool // AttestTimely fixes #8185. It is gated behind a flag to ensure beacon node's fix can safely roll out first. We'll invert this in v1.1.0.

	EnableSlasher                   bool // Enable slasher in the beacon node runtime.
	EnableSlashingProtectionPruning bool // EnableSlashingProtectionPruning for the validator client.

	SaveFullExecutionPayloads bool // Save full beacon blocks with execution payloads in the database.
	EnableStartOptimistic     bool // EnableStartOptimistic treats every block as optimistic at startup.

	DisableResourceManager     bool // Disables running the node with libp2p's resource manager.
	DisableStakinContractCheck bool // Disables check for deposit contract when proposing blocks

	EnableVerboseSigVerification bool // EnableVerboseSigVerification specifies whether to verify individual signature if batch verification fails
	EnableEIP4881                bool // EnableEIP4881 specifies whether to use the deposit tree from EIP4881

	PrepareAllPayloads bool // PrepareAllPayloads informs the engine to prepare a block on every slot.
	// BlobSaveFsync requires blob saving to block on fsync to ensure blobs are durably persisted before passing DA.
	BlobSaveFsync bool
	// KeystoreImportDebounceInterval specifies the time duration the validator waits to reload new keys if they have
	// changed on disk. This feature is for advanced use cases only.
	KeystoreImportDebounceInterval time.Duration

	// AggregateIntervals specifies the time durations at which we aggregate attestations preparing for forkchoice.
	AggregateIntervals [3]time.Duration
}

Flags is a struct to represent which features the client will perform on runtime.

func Get

func Get() *Flags

Get retrieves feature config.