Migrating Solana programs to SBPFv3

Anza published Migrating Solana Programs to SBPFv3 (Joe Caulfield, 16 September 2026). SBPFv3 is the new bytecode. SIMD-0500, planned for Agave v4.4, will reject new deployments, upgrades, and finalizations of programs built for older bytecode. Already-deployed programs keep executing. Teams still on v0–v2 need a rebuild, a test pass, then an upgrade before that gate.

The VM crate is anza-xyz/sbpf. The builder is anza-xyz/cargo-build-sbf. Agave notes stay: v4.2, Anza validator.

What v3 is

Three SIMDs: 0178 static syscalls, 0189 stricter ELF headers, 0377 eBPF ISA compatibility. Mainnet-beta support landed in June with feature 5cC3foj77CWun58pC51ebHFUWavHWKarWyR5UUik7dnC. v3 is not a superset of v2. It reverts SIMD-0173 and SIMD-0174: PQR (udiv, urem, sdiv, srem, lmul) is gone; lddw, neg, and le come back.

Toolchain

Blog mins: platform-tools v1.56 (Rust 1.89.0, LLVM 20), cargo-build-sbf v4.2.0, solana-define-syscall v3.0.0. The cargo-build-sbf README also lists Solana CLI v4.0.0, Pinocchio v0.10, and platform-tools v1.53 as the first v3-capable tools (v1.56 recommended). It names SIMD-500 for Agave v4.3. The blog names SIMD-0500 for Agave v4.4. Use the blog numbers for the migrate; watch both repos.

cargo install cargo-build-sbf --force
cargo build-sbf --arch v3 --tools-version v1.56
readelf -h program.so | grep Flags:

Flags 0x3 is v3. Do not pass --arch v3 to platform-tools older than v1.53. ALU32 is unstable except on v2. Anza does not recommend it.

What breaks

Syscalls go through define_syscall! in solana-define-syscall v3. Older crates or extern "C" leave an unresolved symbol. That becomes call -1. Deploy still succeeds. Invoke loops until CallDepthExceeded. cargo-build-sbf v4.2.0 passes -z defs so the linker fails at build. Pass it yourself in RUSTFLAGS if you use another builder.

Null reads: v3 maps read-only data at VM address 0. A load that aborted on v0 can succeed. Safe Rust will not build that pointer. unsafe, C, and assembly can. Stack frames are contiguous. The compiler may print Error: for overflow without failing the build.

Schedule

1. Bump tools: platform-tools v1.56+, cargo-build-sbf v4.2.0+, define-syscall v3.0.0+.
2. Rebuild cargo build-sbf --arch v3.
3. Keep -z defs on.
4. Confirm readelf -h program.so shows CPU Version 3.
5. Test on Mollusk, LiteSVM, Surfpool, or Anchor before any cluster.
6. Upgrade the on-chain program. Do not wait for the SIMD date.

Working example: buffalojoec/hello-sbpfv3. Follow @anza_xyz for SIMD-0500 activation.

Resources

• Anza migration guide
• anza-xyz/sbpf
• cargo-build-sbf