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 (
	// ToledoTestnet flag for the multiclient eth2 testnet.
	ToledoTestnet = &cli.BoolFlag{
		Name:  "toledo",
		Usage: "This defines the flag through which we can run on the Toledo Multiclient Testnet",
	}
	// PyrmontTestnet flag for the multiclient eth2 testnet.
	PyrmontTestnet = &cli.BoolFlag{
		Name:  "pyrmont",
		Usage: "This defines the flag through which we can run on the Pyrmont Multiclient Testnet",
	}
	// Mainnet flag for easier tooling, no-op
	Mainnet = &cli.BoolFlag{
		Value: true,
		Name:  "mainnet",
		Usage: "Run on Ethereum 2.0 Main Net. This is the default and can be omitted.",
	}
)

var BeaconChainFlags = append(deprecatedFlags, []cli.Flag{
	devModeFlag,
	writeSSZStateTransitionsFlag,
	kafkaBootstrapServersFlag,
	disableGRPCConnectionLogging,
	attestationAggregationStrategy,
	ToledoTestnet,
	PyrmontTestnet,
	Mainnet,
	disableBlst,
	disableEth1DataMajorityVote,
	enablePeerScorer,
	enableLargerGossipHistory,
	checkPtInfoCache,
	disablePruningDepositProofs,
	enableSyncBacktracking,
}...)

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

var E2EBeaconChainFlags = []string{
	"--attestation-aggregation-strategy=max_cover",
	"--dev",
	"--use-check-point-cache",
}

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

var E2EValidatorFlags = []string{}

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

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

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

var ValidatorFlags = append(deprecatedFlags, []cli.Flag{
	writeWalletPasswordOnWebOnboarding,
	enableExternalSlasherProtectionFlag,
	ToledoTestnet,
	PyrmontTestnet,
	Mainnet,
	disableAccountsV2,
	disableBlst,
}...)

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

	// Feature related flags.
	WriteSSZStateTransitions           bool // WriteSSZStateTransitions to tmp directory.
	SkipBLSVerify                      bool // Skips BLS verification across the runtime.
	EnableBlst                         bool // Enables new BLS library from supranational.
	PruneEpochBoundaryStates           bool // PruneEpochBoundaryStates prunes the epoch boundary state before last finalized check point.
	EnableSnappyDBCompression          bool // EnableSnappyDBCompression in the database.
	SlasherProtection                  bool // SlasherProtection protects validator fron sending over a slashable offense over the network using external slasher.
	EnableNoise                        bool // EnableNoise enables the beacon node to use NOISE instead of SECIO when performing a handshake with another peer.
	EnableEth1DataMajorityVote         bool // EnableEth1DataMajorityVote uses the Voting With The Majority algorithm to vote for eth1data.
	EnablePeerScorer                   bool // EnablePeerScorer enables experimental peer scoring in p2p.
	EnablePruningDepositProofs         bool // EnablePruningDepositProofs enables pruning deposit proofs which significantly reduces the size of a deposit
	EnableSyncBacktracking             bool // EnableSyncBacktracking enables backtracking algorithm when searching for alternative forks during initial sync.
	EnableLargerGossipHistory          bool // EnableLargerGossipHistory increases the gossip history we store in our caches.
	WriteWalletPasswordOnWebOnboarding bool // WriteWalletPasswordOnWebOnboarding writes the password to disk after Prysm web signup.

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

	// Slasher toggles.
	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.
	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.