Feature Gates

Feature gates are on-chain switches that activate protocol and runtime behavior at specific points in a cluster’s lifecycle. Private clusters can behave differently from mainnet because feature activation is part of the network state; a deployment can look correct locally and still fail after it meets a different feature set elsewhere.

Inspect before changing anything

solana feature status --url <cluster-rpc-url>

Capture the output with the cluster genesis hash, Agave version, and date. That snapshot is the baseline for test environments and upgrade investigations.

Also capture the validator binary version and the target network endpoint used for the comparison:

agave-validator --version
solana cluster-version --url <target-rpc-url>
solana genesis-hash --url <target-rpc-url>
solana feature status --url <target-rpc-url>

A practical policy

1. Identify the target network whose behavior matters, usually mainnet or the intended testnet.
2. Record its relevant feature status before creating or changing a private cluster.
3. Decide which feature activations must match the target and why.
4. Apply the decision at genesis where required; do not make ad-hoc feature changes mid-test without recording them.
5. Repeat the comparison before release and after an Agave upgrade.

Why this matters

Feature mismatch is a common explanation for “works on our chain, breaks on mainnet.” Treat feature state as a compatibility input alongside program versions, genesis configuration, and RPC behavior.

Change-control record

Every feature decision should state the feature public key, desired activation state, target-network observation, private-cluster decision, reason, approver, and test evidence. The record matters because feature changes can alter runtime semantics without changing your application’s deployment artifact.

Never use a private environment to “turn off whatever breaks the test” without recording the divergence. That creates a testnet that proves less than nothing about production behavior.