Mike Hale Anza's Joe Caulfield has published a migration guide for SBPFv3, the new bytecode format that will become the only deployable format on Solana once SIMD-0500 activates. Programs already deployed keep running under the old format, but more than 17,000 mainnet programs will need a rebuild before they can be upgraded once the change goes live.
No activation date has been set. Anza's advice is to migrate now rather than wait for one.
What SBPFv3 changes and why it exists
SBPFv3 is a bytecode format built from three accepted proposals:
SIMD-0178 for static syscalls
SIMD-0189 for stricter ELF headers
SIMD-0377 for eBPF instruction set compatibility
It has been available since early 2026 and gained mainnet-beta support in June with the activation of feature gate 5cC3foj77CWun58pC51ebHFUWavHWKarWyR5UUik7dnC.
The change that carries the most weight is static syscalls.
Under SBPFv0, a call to something like sol_log_ compiles to a placeholder that the loader resolves against the symbol table every time the program is loaded. Under SBPFv3, the compiler bakes a murmur32 hash of the syscall name directly into the call instruction, so there is nothing left to resolve.
Runtime relocations are no longer supported at all, and SIMD-0178 notes that removing them moves the VM closer to eliminating relocations entirely, which it describes as bringing considerable performance improvements.
SBPFv3 is not a superset of SBPFv2, despite the version number. It reverts the encoding and arithmetic changes from SIMD-0173 and SIMD-0174, dropping the PQR instruction class and restoring lddw, neg, and le.
SBPFv3 also removes stack frame gaps, so all stack frames are now contiguous. If your program was running close to the 4096-byte stack limit before, re-measure it after you rebuild.
Do already-deployed programs break?
Programs already running SBPFv0, v1, or v2 keep executing without restriction, and SIMD-0500 states that execution of those versions remains supported for now.
SIMD-0500 blocks program management.
After the feature activates, loader-v3 returns InstructionError::InvalidAccountData when the ELF is older than SBPFv3. Writing to a buffer, extending a program, and closing an account are unaffected.
Anything under active development stops being upgradeable the moment the gate flips, and the fix at that point is the same rebuild you could do today.
SIMD-0500 includes a count of the mainnet programs still deployed on each old bytecode version, broken out by loader and measured with Blueshift's program-sync tool:
Loader | SBPFv0 | SBPFv1 | SBPFv2 |
|---|---|---|---|
Loader-v1 (finalized) | 136 | 0 | 0 |
Loader-v2 (finalized) | 315 | 0 | 0 |
Loader-v3 (finalized) | 422 | 0 | 0 |
Loader-v3 (upgradable) | 17,279 | 12 | 41 |
The 873 finalized programs cannot be upgraded under any bytecode version, so nothing changes for them. The 17,332 upgradeable loader-v3 programs are the ones that need rebuilding.
Activation: SIMD-0500, planned for Agave v4.4. The proposal is still marked status Idea with its feature key listed as TBD, and Anza points developers at @anza_xyz and the Solana Tech Discord for the announcement. When it lands, deploys, upgrades, and finalizations of pre-SBPFv3 programs start failing.
The tool versions you need
Anza recommends the latest of everything, with these as the floor:
Component | Minimum | Notes |
|---|---|---|
platform-tools | v1.56 | Ships Rust 1.89.0 and LLVM 20 |
cargo-build-sbf | v4.2.0 | Errors on unresolved symbols at build time instead of at runtime |
solana-define-syscall | v3.0.0 | First version with the static syscall syntax |
Rebuilding is one command:
cargo build-sbf --arch v3
Check your platform-tools version before you run it. Anything older than v1.53 can produce a format that is not SBPFv3 compatible even with the flag set, and Anza's guide covers how to confirm the version you ended up with.
You will not be typing the flag for long. A pull request making SBPFv3 the default target merged on September 16, so future releases will build v3 without it.
A demo repo builds both formats side by side
Caulfield also published buffalojoec/hello-sbpfv3, a minimal Pinocchio hello-world that builds for both formats and diffs the results.
For most Rust programs the migration is a toolchain update and a rebuild, which is why Anza is comfortable pushing it without a date. The cost falls on the 17,332 upgradeable programs still on old bytecode, whose maintainers will meet the gate on the day they need to ship a fix.