Blog Article

Protocol 20 Upgrade Guide

Author

Stellar Development Foundation

Publishing date

Protocol upgrade

Soroban

On February 20 at 1700 UTC, the Stellar Mainnet upgraded to Protocol 20, which brings smart contract functionality to the Stellar network. This guide is designed to help businesses and developers who have not done so already to upgrade to Protocol 20 now that it’s live on Mainnet. To ensure that your project, protocol, product or service is compatible with Protocol 20, please check that your Stellar-related software is up to date.

To stay on top of important Protocol 20 development discussions, join the Discord or the dev-mailing list, and read the Protocol 20 Upgrade vote blog post.

Key dates

February 6: Testnet Reset + Upgrade. Complete!
February 9: Stellar Core v20.2.0. Complete!
February 20: Protocol 20 Upgrade Vote + Phase 0. Complete!
March 19: Phase 2 Network Settings Vote. Complete!
Stellar Mainnet supports smart contracts! Deploy when ready!

What do you need to do to ensure your Stellar integration is compatible?

Now that the network has upgraded to Protocol 20, you must install up-to-date versions of any and all Stellar-related software you use. If you fail to do so, your Stellar integration will be incompatible with Protocol 20 and will likely break.

If you use a Stellar SDK

You should be running the latest version of the SDK. Even if your application doesn’t involve Soroban-related functionality, it’s necessary to upgrade your SDK so that it can decode Soroban-related operations, which it may encounter while ingesting network data.

Fair warning: if you are updating the JS SDK, and you haven’t done so in a while, the process may take extra time and effort due to breaking changes that overhauled the build system introduced in v9.0.0. For more information, check out the JS SDK Migration Guide.

If you run Testnet 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 v20.2.0 or above.

If you run Mainnet infrastructure

Upgrade to the latest release of Stellar Core and/or Horizon. You should be on Stellar Core v20.2.0 or above.

Important: The Horizon release compatible with Protocol 20 requires a state rebuild, the first state rebuild since the release made last year. To avoid downtime during this rebuild, see the Scaling documentation: we recommend having a redundant hot backup.

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 plan to 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

You can view current network settings, see a history of protocol upgrades, and see pending proposals for future upgrades here: 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

Protocol 20 releases

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

SDKs

JavaScript Base
JavaScript SDK (now includes Soroban RPC client)
Go (horizonclient & txnbuild)
Java
Python
iOS
PHP
C# .NET (not available yet)
Flutter
Elixir Stellar SDK

Along with the Protocol 20 JavaScript SDK releases linked above, the soroban-client has also been updated, 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.

Context

Since January 2022, collaborators across the Stellar ecosystem have been hard at work on Soroban, a batteries-included, developer-friendly platform that will add smart contract functionality to Stellar. Over the course of 10 releases on the Futurenet (a rough-and-tumble developer test network) and three on the “capital T” Testnet (the more stable ecosystem-wide test network), developers experimented, prototyped, and provided feedback, and the Soroban stack was vetted, hardened, and refined.

At this point, stable releases of all Protocol-20-enabled software — which is the protocol version that enables Soroban capabilities — are available.

Now that the public network has upgraded to Protocol 20, the goal is to get every project in the ecosystem that has not done so already to upgrade their software to ensure continued compatibility, avoid breakage and downtime, and prevent unforced errors.

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

Breaking Changes

As per usual, older versions of Stellar software will not work very well — if at all — now that the network has upgraded to a new protocol version. Right now, both Testnet and Mainnet are running Protocol 20, which means that old versions of Stellar Core won’t work at all, and old versions of Horizon and the Stellar SDKs will likely stop when they encounter something they don’t recognize (like a Soroban transaction). To continue building, upgrade ASAP. In addition to general compatibility issues, here are a few other changes to be aware of:

Horizon and RPC:

There are protocol-breaking changes in the February 6 Testnet reset patch. See the full list of changes in this patch.

Horizon:

Requires a state rebuild. See the Scaling documentation for more information on how to prepare for potential downtime.

JavaScript Base and JavaScript SDK :

Naming for NPM package `@stellar/stellar-base` has been renamed from `stellar-base`.
Naming for NPM package `@stellar/stellar-sdk` has been renamed from `stellar-sdk`.
Node 18 is the new minimum version to use the SDKs.
The soroban-client library has been merged into the `@stellar/stellar-sdk` package, causing significant breaking changes outlined in a migration guide.
See release notes linked above for all breaking changes caused by these package updates.

Changelog

03/19/2024 — Phase 2 is complete. Now this guide will help any stragglers upgrade.

03/15/2024 — The Phase 2 update vote is scheduled for March 19. Added key dates and instructions to reflect this scheduled vote.

02/27/2024 — The network is now in Phase 1. The next step will be the Phase 2 vote, date TBD. Context and additional instructions were added following this update.

02/21/2024 — Updated Key Dates to include scheduled Phase 1 vote date and included instructions for validators to vote to increase the limits to move the network to Phase 1.

02/20/2024 — Validators voted to upgrade the public network to Protocol 20, bringing smart contract functionality to Stellar. Context, updates, and additional instructions were added following the Mainnet upgrade vote that occurred on February 20.

02/09//2024 — Stellar Core v20.2.0 became available: the copy was updated with new instructions for operators of network infrastructure.

02/06/2024 — Updated timeline and copy to reflect the fact that the Testnet upgraded successfully.

01/30/2024 — Updated Protocol 20 upgrade instructions and timelines, including the new target vote date scheduled for February 20.

01/29/2024 — Added context regarding SDF’s decision to disarm its validators in favor of postponing the Protocol 20 upgrade vote.

12/19/2023 — Updated to point out that the Testnet upgrade is complete, stable releases are available for all Protocol 20 software, the Mainnet upgrade vote is scheduled for January 30, and everyone has until then to install Protocol 20 software

12/13/2023 — Added information regarding Horizon state rebuild and related upgrade instructions.

12/12/2023 — Corrected information for entities running Testnet infrastructure: upgrades to Stellar Core and Horizon should occur after the Testnet reset on December 18, not before.

12/11/2023 — Added Testnet release versions of Stellar Core and Horizon.

12/8/2023 — Added links, notes, and breaking changes for stable Protocol 20 JavaScript SDK releases.

Next steps

More for you to explore

Article

November 13, 2023

Protocol 20: Preparing for Smart Contracts on Stellar

Smart Contracts

Developers

Discover the upcoming Protocol 20 upgrade on the Stellar network, introducing Soroban smart contracts. Learn about the development process, impact on…

Learn More