featureconfig

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

Variables

var BeaconChainFlags = append(deprecatedFlags, []cli.Flag{
	devModeFlag,
	customGenesisDelayFlag,
	minimalConfigFlag,
	e2eConfigFlag,
	writeSSZStateTransitionsFlag,
	disableForkChoiceUnsafeFlag,
	disableDynamicCommitteeSubnets,
	disableSSZCache,
	initSyncVerifyEverythingFlag,
	skipBLSVerifyFlag,
	kafkaBootstrapServersFlag,
	enableBackupWebhookFlag,
	enableSlasherFlag,
	cacheFilteredBlockTreeFlag,
	disableStrictAttestationPubsubVerificationFlag,
	disableUpdateHeadPerAttestation,
	enableStateGenSigVerify,
	checkHeadState,
	enableNoiseHandshake,
	dontPruneStateStartUp,
	disableBroadcastSlashingFlag,
	disableInitSyncBatchSaveBlocks,
	waitForSyncedFlag,
	skipRegenHistoricalStates,
	disableInitSyncWeightedRoundRobin,
	disableFieldTrie,
	disableStateRefCopy,
	disableNewStateMgmt,
	enableKadDht,
	disableReduceAttesterStateCopy,
	slasherP2P,
}...)

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

var E2EBeaconChainFlags = []string{
	"--cache-filtered-block-tree",
	"--enable-state-gen-sig-verify",
	"--check-head-state",
	"--slasher-p2p",
}

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

var E2EValidatorFlags = []string{
	"--wait-for-synced",
	"--enable-protect-attester",
	"--enable-protect-proposer",
}

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

var SlasherFlags = append(deprecatedFlags, []cli.Flag{
	e2eConfigFlag,
	enableHistoricalDetectionFlag,
	disableLookbackFlag,
}...)

SlasherFlags contains a list of all the feature flags that apply to the slasher client.

var ValidatorFlags = append(deprecatedFlags, []cli.Flag{
	minimalConfigFlag,
	e2eConfigFlag,
	enableProtectAttesterFlag,
	enableProtectProposerFlag,
	enableExternalSlasherProtectionFlag,
	disableDomainDataCacheFlag,
	waitForSyncedFlag,
}...)

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 ConfigureSlasher

func ConfigureSlasher(ctx *cli.Context)

ConfigureSlasher sets the global config based on what flags are enabled for the slasher 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 {
	// Configuration related flags.
	MinimalConfig bool // MinimalConfig as defined in the spec.
	E2EConfig     bool //E2EConfig made specifically for testing, do not use except in E2E.

	// Feature related flags.
	WriteSSZStateTransitions                   bool // WriteSSZStateTransitions to tmp directory.
	InitSyncNoVerify                           bool // InitSyncNoVerify when initial syncing w/o verifying block's contents.
	DisableDynamicCommitteeSubnets             bool // Disables dynamic attestation committee subnets via p2p.
	SkipBLSVerify                              bool // Skips BLS verification across the runtime.
	EnableBackupWebhook                        bool // EnableBackupWebhook to allow database backups to trigger from monitoring port /db/backup.
	PruneEpochBoundaryStates                   bool // PruneEpochBoundaryStates prunes the epoch boundary state before last finalized check point.
	EnableSnappyDBCompression                  bool // EnableSnappyDBCompression in the database.
	ProtectProposer                            bool // ProtectProposer prevents the validator client from signing any proposals that would be considered a slashable offense.
	ProtectAttester                            bool // ProtectAttester prevents the validator client from signing any attestations that would be considered a slashable offense.
	SlasherProtection                          bool // SlasherProtection protects validator fron sending over a slashable offense over the network using external slasher.
	SlasherP2P                                 bool // SlasherP2P use less restrictive p2p validation for beacon nodes that have a connected slasher.
	DisableStrictAttestationPubsubVerification bool // DisableStrictAttestationPubsubVerification will disabling strict signature verification in pubsub.
	DisableUpdateHeadPerAttestation            bool // DisableUpdateHeadPerAttestation will disabling update head on per attestation basis.
	EnableDomainDataCache                      bool // EnableDomainDataCache caches validator calls to DomainData per epoch.
	EnableStateGenSigVerify                    bool // EnableStateGenSigVerify verifies proposer and randao signatures during state gen.
	CheckHeadState                             bool // CheckHeadState checks the current headstate before retrieving the desired state from the db.
	EnableNoise                                bool // EnableNoise enables the beacon node to use NOISE instead of SECIO when performing a handshake with another peer.
	DontPruneStateStartUp                      bool // DontPruneStateStartUp disables pruning state upon beacon node start up.
	NewStateMgmt                               bool // NewStateMgmt enables the new state mgmt service.
	EnableFieldTrie                            bool // EnableFieldTrie enables the state from using field specific tries when computing the root.
	NoInitSyncBatchSaveBlocks                  bool // NoInitSyncBatchSaveBlocks disables batch save blocks mode during initial syncing.
	EnableStateRefCopy                         bool // EnableStateRefCopy copies the references to objects instead of the objects themselves when copying state fields.
	WaitForSynced                              bool // WaitForSynced uses WaitForSynced in validator startup to ensure it can communicate with the beacon node as soon as possible.
	SkipRegenHistoricalStates                  bool // SkipRegenHistoricalState skips regenerating historical states from genesis to last finalized. This enables a quick switch over to using new-state-mgmt.
	EnableInitSyncWeightedRoundRobin           bool // EnableInitSyncWeightedRoundRobin enables weighted round robin fetching optimization in initial syncing.
	ReduceAttesterStateCopy                    bool // ReduceAttesterStateCopy reduces head state copies for attester rpc.
	EnableKadDHT                               bool // EnableKadDHT stops libp2p's kademlia based discovery from running.
	// DisableForkChoice disables using LMD-GHOST fork choice to update
	// the head of the chain based on attestations and instead accepts any valid received block
	// as the chain head. UNSAFE, use with caution.
	DisableForkChoice bool

	// Slasher toggles.
	DisableBroadcastSlashings bool // DisableBroadcastSlashings disables p2p broadcasting of proposer and attester slashings.
	EnableHistoricalDetection bool // EnableHistoricalDetection disables historical attestation detection and performs detection on the chain head immediately.
	DisableLookback           bool // DisableLookback updates slasher to not use the lookback and update validator histories until epoch 0.

	// Cache toggles.
	EnableSSZCache          bool // EnableSSZCache see https://github.com/prysmaticlabs/prysm/pull/4558.
	EnableEth1DataVoteCache bool // EnableEth1DataVoteCache; see https://github.com/prysmaticlabs/prysm/issues/3106.
	EnableSlasherConnection bool // EnableSlasher enable retrieval of slashing events from a slasher instance.
	EnableBlockTreeCache    bool // EnableBlockTreeCache enable fork choice service to maintain latest filtered block tree.

	KafkaBootstrapServers string // KafkaBootstrapServers to find kafka servers to stream blocks, attestations, etc.
	CustomGenesisDelay    uint64 // CustomGenesisDelay signals how long of a delay to set to start the chain.
}

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

func Get

func Get() *Flags

Get retrieves feature config.