Protocol 21 Upgrade Guide

Now that the network has upgraded to Protocol 21, you must install up-to-date versions of any and all Stellar-related software you use to ensure continued compatibility with the network!

Also, be sure to re-upload your existing Wasms that were created in Protocol 20 to reduce the cost of invoking them and make further executions cheaper, especially as the cost of the re-upload is much lower than the cost of initial upload. To do this re-upload, use the soroban contract install CLI command.

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 Testnet

The list of releases required to support Protocol 21 on Testnet has been updated on the release page of the docs. At this point, stable releases of Stellar Core, Horizon, RPC, the JS SDK, several other SDKs, and the CLI are available. Make sure to install up-to-date versions of any and all Stellar-related software, using the following command:

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

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

Be sure to upgrade Stellar Core to v21.0.0, if you have not done so already.

You should also make sure to set the DEPRECATED_SQL_LEDGER_STATE flag when you deploy the package.

Context: Stellar-core version 21.0 introduces 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).

Operators running a captive-core as part of Horizon or RPC will have the flag set automatically, unless they are still using "in-memory" mode (configured via CAPTIVE_CORE_USE_DB=false), in which case they must set CAPTIVE_CORE_USE_DB=true. Note that this means "in-memory" mode is effectively disallowed by captive-cores starting in Protocol 21.

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.

To view current network settings, see a history of protocol upgrades, and see pending proposals for future upgrades, take a look at https://stellar.expert/explorer/public/protocol-history

In the future, there will be more votes to adjust network settings based on network usage as well as subsequent protocol upgrades, so please make sure to stay up to date on the #validators channel on the Stellar Dev Discord. It’s crucial for validators to stay informed and participate in network governance!

If you are interested in learning more about Soroban network settings, see the docs: https://github.com/stellar/stellar-core/blob/master/docs/software/soroban-settings.md

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.

On June 18, validators voted to upgrade the network to Protocol 21, which brings five CAPs introducing new features, such as passkey signing support and an improvement to state archival, 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

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.