Blog Article
Protocol 20 Upgrade Guide
Author
Stellar Development Foundation
[Publishing date]
Protocol upgrade
Soroban
This guide is designed to help businesses and developers prepare for Protocol 20 in advance of the February 20, 1700 UTC Mainnet validator upgrade vote. 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 in advance of the vote.
To stay on top of important Protocol 20 development discussions, join the Discord or the dev-mailing list.
Key dates
- February 6: Testnet Reset + Upgrade. Complete!
- February 9: Stellar Core v20.2.0. Available now!
- February 20, 1700 UTC: Protocol 20 Upgrade Vote + Phase 0
To ensure network performance and stability, smart contract functionality will be rolled out in phases. Initially, if and when validators approve the upgrade to Protocol 20, network resource limits will be too low to support production-level use. Validators will increase them based on feedback from network operators, then again based on feedback from smart contract developers, until finally they are high enough to allow users to take full advantage of the new functionality. For more info, see the blog post detailing the phased rollout plan.
What do you need to do to prepare?
Before the public network upgrade to Protocol 20, 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 it will likely break if and when an upgrade occurs.
Also, please note that deploying this version of Stellar Core to the Testnet required a Testnet reset on February 6. If you are missing Testnet data, that is probably why.
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.
If you upgraded in advance of the original January 30 date, you don’t need to upgrade again. The changes introduced in Stellar Core v20.2.0 don’t have an impact that far up the stack.
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 Stellar Core to the latest version. If you use Docker images, pull the latest from the Docker registry. The Testnet reset on February 6 was coupled with a software upgrade, and the old versions of Stellar Core and Horizon are no longer compatible with the Testnet. If you are having issues with your Testnet infrastructure, that’s probably why.
If you run Mainnet infrastructure
Upgrade to the stable release of Stellar Core and/or Horizon before the public network upgrade to Protocol 20. Even if you upgraded prior to the original January 30 vote date, you will need to upgrade again. The newest version of Stellar Core, which contains the fix for the bug mentioned above, isn’t compatible with the earlier version that contains the bug. You should be on Stellar Core v20.2.0 or above.
If you run a validator and would like to arm it for the February 20 upgrade, use the upgrade command:
$ stellar-core http-command 'upgrades?mode=set&upgradetime=2024-02-20T17:00:00Z&protocolversion=20'
For more information, check out the Upgrading the Network section of the Run a Core Node docs. To ask questions, stay on top of new information, and communicate with other validators about the upgrade, head to the #validators channel on the Stellar Dev Discord.
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.
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.
Before the public network upgrade to Protocol 20, the goal is to get every project in the ecosystem to upgrade their software to ensure continued compatibility, avoid breakage and downtime, and prevent unforced errors. Upgrade votes are programmatic — they’re part of a regular round of consensus — and when they go through, an upgrade takes immediate effect. Because the Protocol 20 upgrade introduces new network settings that validators control, it is also likely that the initial upgrade vote will be followed by a series of additional votes to adjust those settings. In other words, the limited capacity for Soroban transactions on Mainnet means that Soroban dapps won’t be ready for use at scale until later phases. This deliberate strategy will allow network participants to monitor smart contract functionality's impact on network performance, security, and stability. For more info about the phased rollout, check out The Stellar Network’s Phased Rollout of Smart Contracts: The Road to Mainnet.
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 — after the network upgrades to a new protocol version. Right now, the Testnet is 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 on the Testnet, 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.
- 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
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.