Skip to main content
Solana Program Upgrades: 7 Release Checks - Featured image

Solana Program Upgrades: 7 Release Checks

BUILDERZ

BUILDERZ

Share

In this guide

The decisions and working steps ahead.

Check 1: identify the exact onchain program

Check 2: put upgrade authority behind a deliberate policy

Check 3: build from a frozen source and toolchain

A Solana program upgrade can preserve the same program ID while replacing the executable code behind it. That continuity is useful, but it also puts upgrade authority, build provenance, state compatibility, and incident recovery on one critical path.

This guide gives release owners seven checks to run before and after a mainnet upgrade. The output is a release receipt that ties source, toolchain, binary, authority approval, deployed slot, and verification status together.

For instruction-level security review, begin with the Solana program security guide.

Check 1: identify the exact onchain program

Under loader-v3, the address users call is the Program account. That account points to a ProgramData account containing the deployed executable and upgrade metadata.

Start every release by querying the target cluster:

Code examplebash
solana config get
solana program show <PROGRAM_ID>

Record the cluster URL, program ID, loader owner, ProgramData address, current authority, last deployed slot, data length, and balance. Compare them with the repository release configuration.

Never infer the cluster from a browser tab or shell history. A correct binary deployed to the wrong cluster is still a failed release.

Check 2: put upgrade authority behind a deliberate policy

The upgrade authority can replace program code and can close an upgradeable program. A local default wallet is not a production governance model.

Document:

  • the authority address and custody system
  • required approvals and separation of duties
  • transaction construction and signing flow
  • recovery and key-rotation process
  • emergency deployment criteria
  • who can make the program immutable

Transfer authority only after verifying the new address and approval path. Removing authority with --final is irreversible for that program, so treat it as a governed product decision, not post-deploy cleanup.

Immutability removes future code changes. It does not prove that the current code is safe, that external dependencies will remain compatible, or that state has no administrative controls.

Check 3: build from a frozen source and toolchain

A release candidate needs one source revision, a committed lockfile, pinned features, and recorded tool versions. Uncommitted code cannot be reconstructed from a Git commit.

Capture at minimum:

Code examplebash
git rev-parse HEAD
git status --short
rustc --version
solana --version
anchor --version

Anchor's verifiable-build flow uses a controlled container environment because ordinary local builds can differ across machines. Current Anchor documentation exposes anchor build --verifiable and anchor verify, with newer Anchor releases using solana-verify under the hood.

Store the exact build command, program crate, enabled features, lockfile hash, container or toolchain identity, and output path in the release receipt.

Check 4: prove state and interface compatibility

Replacing executable code does not migrate existing accounts. Review every account type the new binary can read or write.

Check:

  1. discriminators and account ownership
  2. serialized field order and sizes
  3. enum variants and default behavior
  4. PDA seed recipes and canonical bumps
  5. instruction discriminators and argument encoding
  6. CPI interfaces and target program IDs
  7. IDL and client compatibility

When layout changes, define a version byte or safe migration path. Test old accounts against the new binary and test new clients against the old binary if rollout can overlap.

The PDA production guide covers namespace changes. The CPI guide covers dependency interfaces and privilege boundaries.

Check 5: test the exact release artifact

Do not rebuild after approval and assume the binary stayed identical. Hash the artifact that passed review:

Code examplebash
shasum -a 256 target/deploy/<PROGRAM_NAME>.so
solana-verify get-executable-hash target/deploy/<PROGRAM_NAME>.so

Run local or test-cluster checks with that artifact. Cover upgrade-specific cases:

  • existing account fixtures deserialize and remain valid
  • authorization and pause paths behave as approved
  • CPI dependencies accept the new instruction graph
  • compute and account-lock behavior stay within limits
  • old client versions fail safely or remain compatible
  • rollback binaries can read any state written by the candidate

If the candidate changes state in a way the previous binary cannot understand, binary rollback alone is not a recovery plan.

Check 6: deploy with observation and a stop rule

Fund the payer for program extension, deployment transactions, and priority fees. The Solana CLI can extend the ProgramData allocation when a new binary is larger, but the release owner should know the expected size and funding requirement before signing.

Choose a deployment window with named observers and a written stop rule. Capture submission signatures, errors, and the resulting deployment slot.

Immediately after deployment:

Code examplebash
solana program show <PROGRAM_ID>
solana program dump <PROGRAM_ID> deployed-program.so
solana-verify get-executable-hash deployed-program.so

Compare the deployed hash with the approved artifact hash. Confirm the authority and ProgramData address did not change unexpectedly.

Program visibility can lag the deployment by a slot. Treat a transient visibility error separately from a persistent wrong-program or wrong-binary incident.

RPC Edge can strengthen submission and observation across RPC paths. It cannot correct a wrong authority, source revision, program ID, or binary.

Check 7: publish verification and monitor behavior

Run source verification after every deployment or upgrade. Anchor can compare a reproducible build with the deployed program, while Solana's verification tooling can record repository, commit, and build metadata for independent checks.

Verification answers a narrow question: does the declared source and build process reproduce the deployed executable? It does not audit the source, prove economic safety, or validate governance.

Publish the program ID, source repository, commit, build instructions, verification result, authority policy, deployment slot, and known interface changes. Monitor errors, compute, transaction success, state invariants, and dependency behavior through the release window.

Use the transaction debugging guide when failures appear only after deployment.

The 7-Check Solana Upgrade Gate

Before closing the release issue:

  1. confirm cluster, program ID, ProgramData address, loader, and current authority
  2. verify the governed authority path and irreversible actions
  3. freeze source, lockfile, features, and toolchain
  4. prove account, PDA, instruction, IDL, and CPI compatibility
  5. approve and hash the exact tested binary
  6. deploy with observers, stop rules, and immediate onchain hash comparison
  7. publish source verification and monitor production invariants

The release receipt should contain no private keys or secret environment values. It should contain enough public evidence for another engineer to reconstruct the build and identify what changed.

FAQ, sources, and next step

Does a verified build mean the program is secure?

No. It shows that source and build inputs reproduce the deployed binary. Security still requires review, tests, monitoring, and sound authority controls.

Should every program become immutable?

No universal answer exists. Immutability reduces upgrade-key risk but removes the ability to patch code. Make the choice through an explicit threat, governance, and lifecycle review.

Can I roll back by deploying the previous binary?

Only if the authority remains available and the previous binary can safely interpret current state. Test that compatibility before the upgrade.

Why verify after every upgrade?

An upgrade replaces the executable. The prior verification no longer proves that the current onchain binary matches the published source revision.

Primary sources

For a release that crosses account migrations, external programs, governance, and RPC delivery, book a Builderz architecture review.

Continue reading

Building on Solana?

Book a 20-minute intro call, or send a short brief. We reply within one business day.

Solana development service