Protocol 21 Upgrade Guide

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 before the May 14 Testnet upgrade. 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.

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:

upgrades?mode=set&upgradetime=2024-06-18T17:00:00Z&protocolversion=21

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:

• CAP-0051 Smart Contract Host Functionality: Secp256r1 Verification
• CAP-0053 Separate host functions to extend the TTL for contract instance and contract code
• CAP-0054 Soroban refined VM instantiation cost model
• CAP-0055 Soroban streamlined linking
• CAP-0056 Soroban intra-transaction module caching

On June 18, after a Testnet upgrade and Stellar Core, Horizon, and RPC stable releases, both 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.