Protocol 21 Upgrade Guide


Nicole Adair

Publishing date

Soroban, the smart contract platform on Stellar, launched on Mainnet following a successful validator vote on February 20, 2024. And after almost three months, another protocol vote is upon us. On June 18, 2024, Stellar public network validators will vote on whether to upgrade the network to Protocol 21, which, if accepted, will activate five new Core Advancement Proposals (CAPs) on Stellar Mainnet.

These five CAPs introduce some exciting new features, such as passkey signing support and an improvement to state archival (authored by community member, tdep), as well as a few overall cost improvements for smart contract transactions.

You can read all about what's included in Protocol 21 in the announcement blog, and stay up to date on any and all Protocol 21-related announcements in the #protocol-21 channel in the Stellar Developer Discord, where the ecosystem coordinates and shares information about the upgrade, or join the dev-mailing list.

Key dates

  • May 14: Testnet upgrade. Complete!
  • May 30: Stable releases of Stellar Core, Horizon, RPC
  • June 11: Testnet reset
  • June 18: Mainnet upgrade vote

What do you need to do to prepare?

If you use Testnet

The list of releases required to support Protocol 21 on Testnet has been updated on the release page of the docs. Please check there to see what you need to install. Because the Testnet upgrade happens before all stable releases are available, you will need to install preview releases of some software. To do that, use the following command:

cargo install --locked soroban-cli --version 21.0.0-preview.1

Stable release will be available soon, and we will keep the list below updated as releases become available. To prepare for the Mainnet upgrade vote, make sure to install up-to-date versions of any and all Stellar-related software you use before June 18, 2024.

Also be sure to re-upload your existing Wasms that were created in Protocol 20 to reduce the cost of invoking them. You can use the soroban contract install CLI command to do this re-upload.

Context: The semantics of CAP-0054 are important to note specifically for existing Wasms uploaded in Protocol 20. CAP-0054 introduces ContractCodeCostInputs that are written along with the Wasm entries uploaded starting in protocol 21 which will tighten the cost model for VM instantiation, but Wasm uploaded in Protocol 20 will be missing ContractCodeCostInputs. Due to the missing inputs, Protocol 20 code will not be able to take advantage of the tightened cost model until they are re-uploaded in Protocol 21, which will write the ContractCodeCostInputs to the existing Wasm entry.

If you use a Stellar SDK

You should be running the latest version of the SDK. We will update the releases section below to indicate when an SDK release with Protocol 21 support is available, so check back if an SDK you use isn’t listed yet.

If you run Stellar infrastructure

Upgrade to the latest release of Stellar Core and/or Horizon. If you use Docker images, pull the latest from the Docker registry. You should be on Stellar Core v21.0.0 or above.

If you use the Soroban RPC

If you run your own, make sure to upgrade your software! If you don’t, please be aware that the Stellar Development Foundation does not offer a free RPC instance for Mainnet, so you may need to choose an infrastructure provider to use. Here’s a list.

If you run a validator

Stellar-core version 21.0 will introduce a new config flag called DEPRECATED_SQL_LEDGER_STATE. If this flag is not set, stellar-core will not be able to start. This flag must be set when a node upgrades to the stellar-core 21.0 package. This flag must be set when the package is deployed, not when the network actually upgrades to Protocol 21.This flag’s default setting, and the setting that most validator operators should use, is DEPRECATED_SQL_LEDGER_STATE=false. If DEPRECATED_SQL_LEDGER_STATE=true, the node may experience performance degradation and fall behind the rest of the network. DEPRECATED_SQL_LEDGER_STATE should only be set to true if you either:

  1. Must run stellar-core with the “in-memory” mode flag.
  2. Directly query data from stellar-core’s SQL backend, and the data being queried is not supported by BucketListDB (see the “Deprecated Features” listed in the Upcoming Database Changes in Protocol 21 blog).

Only operators running a standalone validator or watcher node will need to set this flag. If captive-core is running as part of Horizon or RPC, the flag will automatically be set and no action is required.

For additional information, context, and instructions related to the BucketListDB update, please read the Upcoming Database Changes in Protocol 21 blog and join the Stellar Dev Discord #validators channel.

The Protocol 21 upgrade vote is scheduled for June 18 at 1700 UTC. Here’s the command to arm your nodes for the upgrade:


Protocol 21 releases

Below are up-to-date links to all available relevant releases with the minimum supported version in parenthesis. Please make sure you are running that version or higher before the upgrade vote! In general, please make sure to check release notes for specific instructions and requirements, and unless otherwise indicated, opt for the “Latest Release.”

Stellar infrastructure


Reminder: The soroban-client was updated along with Protocol 20 JavaScript SDK releases, but will no longer be maintained. Users should use the JavaScript SDK for their app needs, including communicating with the Soroban RPC, as future changes will only be made there. Please read the Migration Guide for how to upgrade to that package.


On February 20, 2024, validators voted to upgrade to Protocol 20, introducing Soroban smart contracts to Stellar’s public network. Since then, developers all over the world have been successfully deploying smart contracts to the Stellar Mainnet.

Currently, work is underway up and down the Stellar stack to vet, harden, and put finishing touches on code to support Protocol 21, which introduces five new CAPs to Mainnet. To read more about each of the CAPs included in Protocol 21, see the Protocol 21 announcement blog post and the following links:

On June 18, after the Testnet upgrade (completed May 14) and the Stellar Core, Horizon, and RPC stable releases scheduled for May, Stellar public network validators will vote on whether to upgrade the public network to Protocol 21. Upgrade votes are programmatic — they’re part of a regular round of consensus — and when they go through, the upgrade takes immediate effect.

To stay informed, ask questions, make suggestions, or share intel, make sure to join the Stellar Dev Discord and check out the #protocol-21 channel, which is where the ecosystem is coordinating and sharing information about the upgrade.


05/14/2024 — The Testnet successfully upgraded to Protocol 21 today. Key dates were updated to reflect this upgrade, and version numbers were added to Protocol 21 release links to reflect the minimum supported versions.