Update a Solana validator client with a verifiable release plan

Separate proposal, software support and activation

A protocol proposal describes a possible change. A client release can implement it behind a feature gate. Cluster activation determines when the new behaviour actually applies. These are three separate facts.

Read the exact release channel and target cluster. An alpha or testnet release appearing at the top of GitHub is not automatically the recommended mainnet build.

For a concrete dated example, Agave v4.5.0-beta.0 was published on 6 November 2026 and labelled a testnet release in its official notes. That label matters more to a mainnet operator than its position as the newest tag.

Client families can carry their own patches and compatibility requirements. Record the actual client name and version rather than describing every Agave-derived binary as identical.

Record the running system before changing it

Save the current binary version and build identity, startup arguments, configuration, service definition and relevant host dependencies. Record cluster, identity and vote account.

Keep a protected recovery plan for keys and authority material without copying secrets into public logs or a generic release folder. Verify that the person performing the update knows which key is required for each action.

Read release notes for removed flags, database changes, snapshot requirements, networking changes, resource needs and stream or RPC compatibility. A validator update can also affect consumers connected to its data interfaces.

Check the relevant cluster's current guidance before choosing a target. A migration's minimum version is a dated compatibility requirement, not necessarily the newest recommendation forever.

Obtain and verify the intended artifact

Use the official release path or the project's documented build process. Match architecture, operating system and exact version. Preserve the artifact identity in the change record.

Apply the integrity and provenance checks the project publishes. A copied filename does not prove a binary's origin. Do not replace official verification with an invented checksum from an unrelated mirror.

Prepare the new artifact before the maintenance window. Validate configuration parsing and required flags where the client supports that check. Test in an appropriate non-production environment when the change's risk warrants it.

Read whether the on-disk state can be used by the former version. A previous binary being available does not guarantee a safe database downgrade.

Prepare recovery and verify the running result

Plan one controlled transition

Choose the maintenance timing using current cluster and operator guidance. Account for scheduled opportunities, catch-up needs and any recommended restart procedure; avoid publishing one universal restart rule for every release.

Ensure there is only the intended active voting identity under the client's failover rules. An unmanaged duplicate instance creates a different risk from an ordinary restart.

Save a pre-change health observation. Apply the documented transition and record exact start, stop and version-change times. Keep the operator's access path available during the change.

Set a decision boundary for proceeding or invoking the recovery plan. Recovery can require compatible snapshots or state restoration, not merely pointing a symlink at an older executable.

Verify the new process and its actual service outcome

Confirm the running binary and version from the actual process, then inspect startup logs and effective configuration. A downloaded file is not proof that the service is using it.

Check replay progress, resource pressure, connectivity, admission and participation through suitable local and external evidence. Production opportunities require their own schedule-aware interpretation.

For data consumers, test RPC contracts and streaming fields affected by the release. After Alpenglow, multiple candidate banks and node-local bank_id semantics are relevant to supported streaming integrations.

Keep the before and after observations under consistent definitions. A dashboard provider changing its methodology during the same interval can confound the comparison.

Leave the release decision reproducible

Record the reason for the update, exact target, official notes consulted, artifact identity, configuration changes, maintenance times and verification outcome.

If an incident follows, retain the timeline and evidence before declaring the release the cause. The incident guide provides the causal and timestamp distinctions.

For feature-related work, separately record activation evidence on the target cluster. This prevents a later reader from treating installed support as proof of enabled behaviour.

Common questions