Protocol 23 upgrade guide

This guide is designed to help businesses and developers prepare for Protocol 23 with key dates, release information, a changelog, and more.

You can read all about what's included in Protocol 23 in the announcement blog and stay up to date on any and all Protocol 23-related announcements on the Stellar Developer Discord, where the ecosystem coordinates and shares information about the upgrade.

Key dates

• July 17: Testnet upgrade. Complete!
• August 14: Testnet reset. Complete!
• August 14: Stable releases available. Complete!
• September 3: Mainnet upgrade vote. Complete!

The August 14 Testnet reset will clear all Testnet ledger entries including account, asset, and contract data, so please be prepared to recreate any you need to persist! For tips and more info, see the Testnet docs.

Also, after the August 14 Testnet reset, you will need to upgrade to new versions of Stellar-related software including Stellar Core, RPC, Horizon, and Stellar SDKs as soon as possible to ensure Testnet compatibility even if you installed new versions prior to the July 17 Testnet upgrade.

Apologies for the inconvenience, and for the short notice: normally, we don't reset Testnet as part of a protocol upgrade, but this time it's necessary due to some updates to Stellar Core. The August 14 Testnet reset will replace the previously scheduled Q3 Testnet reset.

If you use a Stellar SDK

For your Testnet integration, upgrade to the latest version of the relevant Stellar SDK on August 14.

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

We will update the releases section below to indicate when an SDK release with Protocol 23 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 Protocol 23 builds from the Docker registry. If you build from source or our Debian packages, make sure to also update your stellar-core, stellar-horizon, and stellar-rpc binaries to the Protocol 23 builds.

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.

If you run a validator

The Protocol 23 upgrade vote is scheduled for September 3, 2025 at 1700 UTC. You should arm your validator with the following command:

upgrades?mode=set&upgradetime=2025-09-03T17:00:00Z&protocolversion=23

Below are up-to-date links to all available releases relevant to Protocol 23. 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

• Stellar Core
• Horizon
• Stellar RPC

SDKs

• Rust SDK
• JavaScript Base
• JavaScript SDK
• Go SDK
  • horizonclient & txnbuild
  • rpcclient
• Java
• Python
• iOS
• PHP
• C# .NET
• Flutter
• Elixir Stellar SDK

Testnet is running Protocol 23, which means that old versions of Stellar Core won’t work at all, and old versions of Horizon, Stellar RPC, Galexie and the Stellar SDKs will likely stop when they encounter something they don’t recognize.

That said, when the Testnet resets August 14, you will need to install stable releases of all Stellar-related software to ensure compatibility with a new Stellar Core release. In addition to general compatibility issues, here are a few other changes to be aware of:

Stellar RPC rebrand

Soroban RPC was officially renamed to Stellar RPC in Protocol 22. While it has continued to be published under both names, starting in Protocol 23 soroban-rpc images and packages will no longer be available.

XDR

• There have been significant breaking changes to the XDR in Protocol 23, the largest of which is the introduction of a new transaction meta structure, TransactionMetaV4, which replaces TransactionMetaV3. Any application that reads raw transaction meta from Stellar Core, Horizon, Stellar RPC, Galexie, etc will be affected. This may include dapps, indexers, exchanges, issuers, and wallets.
• Protocol 23 unifies event streams between Classic operations and Soroban contracts. Key changes include removing admin topics from mint, clawback, and set_authorized events, adding new fee events, and having SAC emit mint/burn events (instead of transfer) when the issuer is involved. Transfer events now support map-based data fields for memo information alongside integers. Classic operations will emit standardized events matching Soroban format for consistent asset movement tracking.
• There will also be a config option that will modify pre-v23 SAC events to follow the admin and issuer related changes mentioned above.
• See CAP-67 and Stellar XDR for more information about the TransactionMetaV4 format.

RPC

• The getLedgerEntry endpoint has been removed
• The pagingToken field of getEvents results has been removed
• The snake_cased fields of getVersionInfo have been removed (commit_hash, etc.)
• Diagnostic events are no longer returned by getEvents
• The inSuccessfulContractCall field of getEvents is now deprecated and will be removed in Protocol 24

Horizon

• Release requires a state rebuild and a database migration. See the Scaling documentation for more information on how to prepare for potential downtime.
• The following configuration flags have been removed
  • CAPTIVE_CORE_USE_DB
  • DEPRECATED_SQL_LEDGER_STATE
• The errorResultXdr field from the response of the async transaction submission endpoint has been removed
• The num_archived_contracts and archived_contracts_amount fields from the /assets response have been removed

SDKs

• horizonclient: Fields removed from the Horizon API (referenced above) have been removed removed
• js-stellar-sdk: Node >= 20 is now required

Changelog

September 3, 2025: Mainnet upgraded to Whisk (Protocol 23)

August 26, 2025: Changed JS SDK Node requirement and breaking changes for RPC has been updated

August 14, 2025: Stable build releases and Testnet reset completed

August 6, 2025: Added to XDR breaking changes

August 4, 2025: Announced Testnet reset August 14, stable releases August 14, and new Mainnet upgrade date of September 3.

July 31, 2025: Updated dates of stable build release and Mainnet vote

July 25, 2025: Updated validator instructions

July 22, 2025: Added the Breaking Changes section

July 17, 2025: Updated timeline to reflect the testnet upgrade, and added Rust SDK to releases.

June 20, 2025: Updated timeline to reflect extra days required for Stellar Core implementation, which pushed Testnet and Mainnet dates back.