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 (
	// AltonaTestnet flag for the multiclient eth2 testnet configuration.
	AltonaTestnet = &cli.BoolFlag{
		Name:  "altona",
		Usage: "This defines the flag through which we can run on the Altona Multiclient Testnet",
	}
	// OnyxTestnet flag for the Prysmatic Labs single-client testnet configuration.
	OnyxTestnet = &cli.BoolFlag{
		Name:  "onyx",
		Usage: "This defines the flag through which we can run on the Onyx Prysm Testnet",
	}
)

var BeaconChainFlags = append(deprecatedFlags, []cli.Flag{
	devModeFlag,
	writeSSZStateTransitionsFlag,
	disableForkChoiceUnsafeFlag,
	disableDynamicCommitteeSubnets,
	disableSSZCache,
	disableInitSyncVerifyEverythingFlag,
	skipBLSVerifyFlag,
	kafkaBootstrapServersFlag,
	enableBackupWebhookFlag,
	cacheFilteredBlockTreeFlag,
	disableStrictAttestationPubsubVerificationFlag,
	disableUpdateHeadPerAttestation,
	enableStateGenSigVerify,
	checkHeadState,
	disableNoiseHandshake,
	dontPruneStateStartUp,
	disableBroadcastSlashingFlag,
	waitForSyncedFlag,
	disableReduceAttesterStateCopy,
	disableGRPCConnectionLogging,
	attestationAggregationStrategy,
	disableNewBeaconStateLocks,
	AltonaTestnet,
	OnyxTestnet,
	batchBlockVerify,
	initSyncVerbose,
	disableFinalizedDepositsCache,
	enableEth1DataMajorityVote,
	enableAttBroadcastDiscoveryAttempts,
	enablePeerScorer,
	enableRoughtime,
	checkPtInfoCache,
}...)

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",
	"--attestation-aggregation-strategy=max_cover",
	"--dev",
	"--enable-eth1-data-majority-vote",
	"--use-check-point-cache",
}

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

var E2EValidatorFlags = []string{
	"--wait-for-synced",
}

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

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

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

var ValidatorFlags = append(deprecatedFlags, []cli.Flag{
	enableLocalProtectionFlag,
	enableExternalSlasherProtectionFlag,
	disableDomainDataCacheFlag,
	waitForSyncedFlag,
	AltonaTestnet,
	OnyxTestnet,
	disableAccountsV2,
}...)

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 {
	// State locks
	NewBeaconStateLocks bool // NewStateLocks for updated beacon state locking.
	// Testnet Flags.
	AltonaTestnet bool // AltonaTestnet defines the flag through which we can enable the node to run on the altona testnet.
	OnyxTestnet   bool // OnyxTestnet defines the flag through which we can enable the node to run on the onyx testnet.
	// 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.
	LocalProtection                            bool // LocalProtection prevents the validator client from signing any messages that would be considered a slashable offense from the validators view.
	SlasherProtection                          bool // SlasherProtection protects validator fron sending over a slashable offense over the network using external 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.
	WaitForSynced                              bool // WaitForSynced uses WaitForSynced in validator startup to ensure it can communicate with the beacon node as soon as possible.
	ReduceAttesterStateCopy                    bool // ReduceAttesterStateCopy reduces head state copies for attester rpc.
	EnableAccountsV2                           bool // EnableAccountsV2 for Prysm validator clients.
	BatchBlockVerify                           bool // BatchBlockVerify performs batched verification of block batches that we receive when syncing.
	InitSyncVerbose                            bool // InitSyncVerbose logs every processed block during initial syncing.
	EnableFinalizedDepositsCache               bool // EnableFinalizedDepositsCache enables utilization of cached finalized deposits.
	EnableEth1DataMajorityVote                 bool // EnableEth1DataMajorityVote uses the Voting With The Majority algorithm to vote for eth1data.
	EnableAttBroadcastDiscoveryAttempts        bool // EnableAttBroadcastDiscoveryAttempts allows the p2p service to attempt to ensure a subnet peer is present before broadcasting an attestation.
	EnablePeerScorer                           bool // EnablePeerScorer enables experimental peer scoring in p2p.
	EnableRoughtime                            bool // EnableRoughtime is an opt-in flag for enabling hourly syncing with roughtime. Default is to not sync.

	// 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

	// Logging related toggles.
	DisableGRPCConnectionLogs bool // Disables logging when a new grpc client has connected.

	// 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.
	UseCheckPointInfoCache  bool // UseCheckPointInfoCache uses check point info cache to efficiently verify attestation signatures.

	KafkaBootstrapServers          string // KafkaBootstrapServers to find kafka servers to stream blocks, attestations, etc.
	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.