sBPFv3 Programs

sBPFv3 Programs

Q4 2026 • Solana Foundation

Every Solana program is compiled into a format called sBPF (Solana Berkeley Packet Filter) before it is deployed. The runtime reads that format to run the program. Over the years there have been four versions of it, v0 through v3, and today validators have to support all four.

SIMD-0500 makes sBPFv3 the only format accepted for new deployments, upgrades, and finalizations. Programs already onchain continue to run unchanged. Only new deployments and upgrades have to use the current format. This means the number of programs using older formats stops growing, which opens a path to retiring those formats later.

For developers, the change is mostly a build-tool update. A supported toolchain produces sBPFv3 automatically. Anza has published a detailed migration guide with the runtime background.

Current feature gate activation status:

Does This Affect Me?

Quick Check: Is Your Program Already on sBPFv3?

Build your program, then read the version flag from the header of the resulting .so file. On Linux, readelf is usually installed. macOS does not ship it, but the Solana platform tools installed by cargo build-sbf include llvm-readelf (the version directory may differ, check ls ~/.cache/solana):

# Linux
readelf -h target/deploy/<PROGRAM_NAME>.so | grep Flags:

# macOS, using the platform tools installed by cargo build-sbf
~/.cache/solana/v1.57/platform-tools/llvm/bin/llvm-readelf -h target/deploy/<PROGRAM_NAME>.so | grep Flags:

An sBPFv3 program prints the flag as 0x3 (some readelf builds append CPU Version: 3):

  Flags:                             0x3

If the flag is 0x3, you are done. If it is 0x0, 0x1, or 0x2, follow the upgrade steps for your framework below.

Technical Details

What the Error Looks Like

After activation, deploying or modifying a program built for an older format fails with a message like this:

  Program BPFLoaderUpgradeab1e11111111111111111111111 invoke [1]
  Detected sbpf_version required by the executable which are not enabled
  Program BPFLoaderUpgradeab1e11111111111111111111111 failed: invalid account data for instruction

It means the feature is active and your program needs to be rebuilt for sBPFv3 with one of the toolchains below.

Toolchain Support for sBPFv3

Step 1: Install Solana CLI v4.3.0

This step applies to every framework. The Solana CLI ships the compiler that produces sBPFv3 output, so do this before the framework-specific steps below.

# New install
sh -c "$(curl -sSfL https://release.anza.xyz/v4.3.0/install)"

# Existing install
agave-install init v4.3.0

# Confirm
solana --version

See the Anza install guide for details. If you cannot install it, follow If You Cannot Install Solana CLI v4.3.0 instead, then return here.

Step 2: Update Your Framework

These are the minimum releases that support building sBPFv3 programs. Pick your framework and follow its steps.

Anchor

1. Install or upgrade AVM (anchor-lang on crates.io):

   curl -sSfL https://raw.githubusercontent.com/otter-sec/anchor/master/avm/install | sh
   

2. Update anchor-lang using the command for your release line:

   cargo add anchor-lang@0.30.2   # 0.30 line
   cargo add anchor-lang@0.31.2   # 0.31 line
   cargo add anchor-lang@0.32.2   # 0.32 line
   

   Or move to Anchor 1.2.0 with avm use 1.2.0.

3. Build and deploy:

   anchor build
   anchor deploy
   

Pinocchio

1. Update pinocchio to the latest version (v0.11.2 at the time of writing):

   cargo add pinocchio
   

   Any release from v0.10 onward builds sBPFv3. Note that v0.11 changed the entrypoint signature to take &mut [AccountView], so moving from v0.10 may need small code changes.

2. Build for sBPFv3 and deploy:

   cargo build-sbf --arch v3
   solana program deploy target/deploy/<PROGRAM_NAME>.so
   

Quasar

1. Build for sBPFv3 with Quasar and deploy:

   cargo build-sbf --arch v3
   quasar deploy
   

Native Rust (solana-program crates)

1. Update solana-program to the latest version. It pulls in the matching solana-define-syscall:

   cargo add solana-program
   

2. Build for sBPFv3 and deploy:

   cargo build-sbf --arch v3
   solana program deploy target/deploy/<PROGRAM_NAME>.so
   

If You Cannot Install Solana CLI v4.3.0

Force-install cargo-build-sbf directly:

cargo install cargo-build-sbf --force

Once you've verified that it has successfully been installed, replace the Solana CLI's cargo-build-sbf binary with a symlink to the force-installed binary:

CARGO_BUILD_SBF="$HOME/.cargo/bin/cargo-build-sbf"
SOLANA_CARGO_BUILD_SBF="$HOME/.local/share/solana/install/active_release/bin/cargo-build-sbf"
rm -rf "$SOLANA_CARGO_BUILD_SBF"
ln -s "$CARGO_BUILD_SBF" "$SOLANA_CARGO_BUILD_SBF"

Then continue the steps for your framework above.

Verify sBPFv3 Programs

solana-verifiable-build uses the Solana version in [workspace.metadata.cli] to select the pinned build image. In the root Cargo.toml for your workspace, add:

[workspace.metadata.cli]
solana = "4.3.0"

With the 4.3.0 toolchain, --arch v3 is the only additional build flag needed. Build locally, or verify the deployed program directly from its repository:

solana-verify build --cargo-build-sbf-args="--arch v3"
solana-verify verify-from-repo --program-id <PROGRAM_ID> --cargo-build-sbf-args="--arch v3" https://github.com/<OWNER>/<REPOSITORY>

If you must remain on the 4.2.0 toolchain, set solana = "4.2.0" in the same [workspace.metadata.cli] section. That toolchain also requires platform tools v1.57, so pass --tools-version v1.57 through to cargo build-sbf:

solana-verify build --cargo-build-sbf-args="--tools-version v1.57 --arch v3"
solana-verify verify-from-repo --program-id <PROGRAM_ID> --cargo-build-sbf-args="--tools-version v1.57 --arch v3" https://github.com/<OWNER>/<REPOSITORY>

Why sBPFv3 Is the New Minimum

Each sBPF version defines which instructions a compiled program may use, how functions call each other, and how the program file (an ELF binary) is laid out. The version is recorded in the file header so the runtime can apply the right rules. Solana currently executes four versions: v0, v1, v2, and v3.

The versions are not a linear list where each one keeps everything before it. v3 drops v2's PQR instructions and dynamic stack frames in favor of a cleaner boundary with upstream eBPF tooling. This means a migration is a rebuild with a supported toolchain, not a header-only version bump.

Three properties make v3 the right minimum:

• Static syscalls. In older formats, the validator has to patch syscall addresses into a copy of the program every time it loads it. v3 resolves them when the program is built, so loading needs less memory and less work.
• Stricter ELF headers. v3 programs leave out dynamic-linking sections they no longer need, so validators parse and validate less metadata.
• eBPF v3 compatibility. Solana-specific instruction behavior is replaced with encodings that LLVM already understands. Compiler maintainers have fewer custom differences to support, and more upstream eBPF tooling becomes reusable.

For developers, all of this stays behind the build process: a supported toolchain emits the required instructions and file structure automatically.

Previous Related SIMDs

SIMD-0377 adds the instructions and encoding changes needed to run code generated for the eBPF v3 instruction set, including 32-bit jump instructions, an eBPF-compatible callx encoding, and the removal of stack-frame gaps for sBPFv3 programs. Programs opt in by setting the sBPF version in their ELF header, so the runtime applies v3 semantics only to programs built for it.

SIMD-0178 lets the compiler resolve syscall references at link time instead of relying on runtime relocations. This removes work from program loading and reduces the dynamic ELF metadata a program has to carry.

About SIMD-0500

sBPFv3 creates a cleaner foundation for Solana program development by aligning the runtime with modern eBPF compiler output and reducing work during program loading. It also gives future compiler and runtime improvements a standardized target without forcing existing deployed programs to migrate immediately.

Learn more: Solana Upgrades