Feature Gate Setup Process

Overview

This page seeks to explain why feature gates are used, how they work, and some of the mechanics for setting them up. Enablement is in a separate wiki page here.

Why Feature Gates?

Feature gates are useful for ensuring the entire cluster is in sync when enabling some capability. Without feature gates, each validator would asynchronously enable the capability whenever they decide to update or pass some config parameter.

How do Feature Gates Work?

Feature gates work by creating a keypair so that features can be identified by a pubkey (and activated via private key). The set of active/inactive features are stored in the Bank, and the set of active features gets updated on epoch boundaries (which is roughly the same time across the cluster). Conditional logic can then be used in the code which queries whether a feature has been activated.

How do I Add a Feature Gate?

Note: These instructions provide mechanics on January '23. It is possible specific commands will have changed since then.

1. Create keypair using solana-keygen tool (make sure to save this so it can be used for activation later!)
2. Link the pubkey to a feature module in feature_set.rs
3. Add the feature module id and short description to the FEATURE_NAMES HashMap in feature_set.rs
4. Add whatever conditional logic is necessary (specific to your feature - e.g. if bank.feature_set.is_active(&feature_set::my_feature::id()))
5. Create a new Feature Gate issue on GitHub. For example, #24352
6. Update the Feature Gate Activation Schedule page
7. After code has been pushed in, refer to Feature Activation Process for next steps