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 funcitonality without losing coverage on the existing functionality. This is considered an opt-in feature flag. Example usage:

func someExistingMethod(ctx context.Context) error {
    if featureconfig.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)
• func ConfigureValidator(ctx *cli.Context)
• func Init(c *Flags)
• func InitWithReset(c *Flags) func()
• type Flags
  • func Get() *Flags

Variables

var (
	// PyrmontTestnet flag for the multiclient Ethereum consensus testnet.
	PyrmontTestnet = &cli.BoolFlag{
		Name:  "pyrmont",
		Usage: "This defines the flag through which we can run on the Pyrmont Multiclient Testnet",
	}
	// PraterTestnet flag for the multiclient Ethereum consensus testnet.
	PraterTestnet = &cli.BoolFlag{
		Name:  "prater",
		Usage: "Run Prysm configured for the Prater test network",
	}
	// Mainnet flag for easier tooling, no-op
	Mainnet = &cli.BoolFlag{
		Value: true,
		Name:  "mainnet",
		Usage: "Run on Ethereum Beacon Chain Main Net. This is the default and can be omitted.",
	}
)

var BeaconChainFlags = append(deprecatedFlags, []cli.Flag{
	devModeFlag,
	writeSSZStateTransitionsFlag,
	disableGRPCConnectionLogging,
	attestationAggregationStrategy,
	PyrmontTestnet,
	PraterTestnet,
	Mainnet,
	enablePeerScorer,
	enableLargerGossipHistory,
	checkPtInfoCache,
	disableBroadcastSlashingFlag,
	disableNextSlotStateCache,
	forceOptMaxCoverAggregationStategy,
	enableSlasherFlag,
	disableProposerAttsSelectionUsingMaxCover,
	disableOptimizedBalanceUpdate,
	enableHistoricalSpaceRepresentation,
	disableCorrectlyInsertOrphanedAtts,
	enableGetBlockOptimizations,
	disableCorrectlyPruneCanonicalAtts,
	disableActiveBalanceCache,
	enableBatchGossipVerification,
}...)

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

var E2EBeaconChainFlags = []string{
	"--attestation-aggregation-strategy=opt_max_cover",
	"--dev",
	"--use-check-point-cache",
	"--enable-active-balance-cache",
}

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 ValidatorFlags = append(deprecatedFlags, []cli.Flag{
	writeWalletPasswordOnWebOnboarding,
	enableExternalSlasherProtectionFlag,
	disableAttestingHistoryDBCache,
	PyrmontTestnet,
	PraterTestnet,
	Mainnet,
	dynamicKeyReloadDebounceInterval,
	attestTimely,
	enableSlashingProtectionPruning,
	enableDoppelGangerProtection,
}...)

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)

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

func ConfigureValidator

func ConfigureValidator(ctx *cli.Context)

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 {
	// Testnet Flags.
	PyrmontTestnet bool // PyrmontTestnet defines the flag through which we can enable the node to run on the Pyrmont testnet.

	// Feature related flags.
	RemoteSlasherProtection             bool // RemoteSlasherProtection utilizes a beacon node with --slasher mode for validator slashing protection.
	WriteSSZStateTransitions            bool // WriteSSZStateTransitions to tmp directory.
	SkipBLSVerify                       bool // Skips BLS verification across the runtime.
	EnablePeerScorer                    bool // EnablePeerScorer enables experimental peer scoring in p2p.
	EnableLargerGossipHistory           bool // EnableLargerGossipHistory increases the gossip history we store in our caches.
	WriteWalletPasswordOnWebOnboarding  bool // WriteWalletPasswordOnWebOnboarding writes the password to disk after Prysm web signup.
	DisableAttestingHistoryDBCache      bool // DisableAttestingHistoryDBCache for the validator client increases disk reads/writes.
	ProposerAttsSelectionUsingMaxCover  bool // ProposerAttsSelectionUsingMaxCover enables max-cover algorithm when selecting attestations for proposing.
	EnableOptimizedBalanceUpdate        bool // EnableOptimizedBalanceUpdate uses an updated method of performing balance updates.
	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
	EnableGetBlockOptimizations         bool // EnableGetBlockOptimizations optimizes some elements of the GetBlock() function.
	EnableBatchVerification             bool // EnableBatchVerification enables batch signature verification on gossip messages.
	// Logging related toggles.
	DisableGRPCConnectionLogs bool // Disables logging when a new grpc client has connected.

	// Slasher toggles.
	DisableLookback           bool // DisableLookback updates slasher to not use the lookback and update validator histories until epoch 0.
	DisableBroadcastSlashings bool // DisableBroadcastSlashings disables p2p broadcasting of proposer and attester slashings.

	// Cache toggles.
	EnableSSZCache           bool // EnableSSZCache see https://github.com/prysmaticlabs/prysm/v2/pull/4558.
	EnableNextSlotStateCache bool // EnableNextSlotStateCache enables next slot state cache to improve validator performance.
	EnableActiveBalanceCache bool // EnableActiveBalanceCache enables active balance cache.

	// 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 for the validator client.
	EnableSlashingProtectionPruning bool

	// Bug fixes related flags.
	CorrectlyInsertOrphanedAtts bool
	CorrectlyPruneCanonicalAtts 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

	AttestationAggregationStrategy string // AttestationAggregationStrategy defines aggregation strategy to be used when aggregating.
}

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

func Get

func Get() *Flags

Get retrieves feature config.