Protocol 22 Upgrade Guide

TL;DR: Before the upgrade, make sure to install up-to-date versions of any and all Stellar-related software you use!

If you use a Stellar SDK

For your Testnet integration, upgrade to the latest version of the relevant Stellar SDK before November 12.

For your Mainnet integration, upgrade to the latest version of relevant Stellar SDKs before December 5.

Note that some SDK maintainers publish release candidate (i.e., RC) versions of the SDK when Stellar Core, Horizon, and RPC release RC versions rather than immediately releasing stable versions. In this case, remember to upgrade to stable versions of the SDK when they are available.

We will update the releases section below to indicate when an SDK release with Protocol 22 support is available, so check back if an SDK you use isn’t listed yet.

If you run Stellar infrastructure

If you use Docker images, pull the latest from the Docker registry. If you build from source or our Debian packages, make sure to also update your stellar-core binary used by your Horizon or RPC instance to the latest.

If you don’t run your own infrastructure but still need access to a Horizon or RPC instance, you can use an infrastructure provider. Here are lists for Horizon and RPC.

A note on Horizon Transaction Meta Default Settings Change: When Protocol 22 goes live, Transaction Meta (tx meta) will no longer be returned by SDF’s hosted Horizon API by default. Instead of using Horizon to access Transaction Meta (tx meta), developers should access it with the RPC or Stellar Core.

Operators hosting their own Horizon can emulate this behavior by configuring the SKIP_TXMETA flag, should they also choose to stop serving Transaction Meta (tx meta). Please bear in mind that we expect the operational burden to be high should you choose to continue serving it.

Context: Transaction metas describe the changes made by a transaction to the state of the ledger. Historically, Horizon has exposed these as part of the transaction resource since its inception in 2015. Now it will be served by the RPC. These metas can grow quite significantly in size. For operators who maintain Horizon with a non-trivial retention window, this could be a significant operation burden.

Notes: RPC will continue to serve transaction metas for transactions within its 7 day retention window.

If you run a validator

The Protocol 22 upgrade vote is scheduled for December 5 at 1700 UTC. Here’s the command to arm your nodes for the upgrade:

upgrades?mode=set&upgradetime=2024-12-05T17:00:00Z&protocolversion=22

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!

Soroban RPC rebrand

Soroban RPC has been officially renamed to Stellar RPC, as it is a fundamental building block for all of Stellar, not just Soroban. Operators should start installing stellar-rpc packages and images, as soroban-rpc packages and images are officially deprecated. Deprecated packages will cease to be published as of Protocol 23.

• 11/12/2024 – Updated key dates to reflect that the Testnet upgrade is complete.
• 11/12/2024 – Added context and instructions related to the Soroban RPC rebrand.
• 11/07/2024 – Added instructions and context related to Horizon Transaction Meta Default Settings Default Behavior Change.