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:
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:
git rev-parse HEAD
git status --short
rustc --version
solana --version
anchor --versionAnchor'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:
- discriminators and account ownership
- serialized field order and sizes
- enum variants and default behavior
- PDA seed recipes and canonical bumps
- instruction discriminators and argument encoding
- CPI interfaces and target program IDs
- 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:
shasum -a 256 target/deploy/<PROGRAM_NAME>.so
solana-verify get-executable-hash target/deploy/<PROGRAM_NAME>.soRun 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:
solana program show <PROGRAM_ID>
solana program dump <PROGRAM_ID> deployed-program.so
solana-verify get-executable-hash deployed-program.soCompare 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:
- confirm cluster, program ID, ProgramData address, loader, and current authority
- verify the governed authority path and irreversible actions
- freeze source, lockfile, features, and toolchain
- prove account, PDA, instruction, IDL, and CPI compatibility
- approve and hash the exact tested binary
- deploy with observers, stop rules, and immediate onchain hash comparison
- 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.
