Blog Article
Protocol 20 Upgrade Guide
Author
Stellar Development Foundation
Publishing date
Protocol upgrade
Soroban
This guide is designed to help developers and businesses building on Stellar prepare for the public network upgrade to Protocol 20, which introduces support for Soroban smart contracts.
Key dates
These dates are estimates, intended to help you plan to take necessary steps to prepare for the Protocol 20 upgrade. They may change over the next few weeks as audits and engineering tests are completed, and as new information comes in. When dates become definite, we will update this guide to let you know.
- December 11 — Stellar Core, Horizon, and Soroban RPC pre-releases / Stellar SDK releases
- December 18 — Testnet network upgrade readiness date and reset (scheduled for 9am PT)
- December 19 — Stellar Core, Horizon, and Soroban RPC stable releases
- January 30, 2024 — Public network upgrade readiness date
What do you need to do to prepare?
Before the January 30, 2024 readiness date, plan to 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.
If you use a Stellar SDK
Upgrade to 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.
If you run Testnet infrastructure
Upgrade to the pre-release versions of Stellar Core and/or Horizon before the December 18 Testnet reset.
If you run Mainnet infrastructure
Upgrade to stable release of Stellar Core and/or Horizon before the January 30 upgrade readiness date.
If your Stellar Core node is set up to validate transactions, you will also need to arm your node to vote for the upgrade. When the upgrade vote date is definite, we will add the command used to do that to this guide, and notify validators via the #validators channel on the Stellar Dev Discord.
Protocol 20 releases
Below are up-to-date links to all available relevant releases. For the time being, you should hold off on using these releases on mainnet. In general, please make sure to check release notes for specific instructions and requirements.
Stellar infrastructure
SDKs
- JavaScript Base (stable Protocol 20 release)
- JavaScript SDK (stable Protocol 20 release; now includes Soroban RPC client)
- Go (horizonclient & txnbuild)
- Java
- Python
- iOS
- PHP
- C# .NET
- Flutter
- Elixir Stellar SDK
Along with the stable 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
On Wednesday, September 20 the Testnet, which is running release candidate versions of Stellar Core and Horizon, upgraded to Protocol 20. Since then, developers all over the world have been successfully deploying smart contracts to the Stellar Testnet, which has been an exciting thing to see.
Currently, work is underway up and down the Stellar stack to vet, harden, and put finishing touches on code, and before the end of the year, stable versions of Stellar Core, Horizon, the RPC, and the Stellar SDKs that support Protocol 20 should be available. Once they are, every project in the ecosystem needs to upgrade to those versions to be ready for the network upgrade, and so we have set a tentative date by which we are expecting you to do that: January 30, 2024, the readiness date.
Some time after that readiness date, Stellar public network validators will vote on whether to upgrade the public network to Protocol 20. Upgrade votes are programmatic — they’re part of a regular round of consensus — and when they go through, the 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. When there is a timeline for any of those votes, we will add them to this guide.
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
JavaScript Base (v10.0.0) and JavaScript SDK (v11.0.1):
- 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.
- See release notes linked above for all breaking changes caused by these package updates.
Changelog
12/8/2023 - Updates to notes and breaking changes for stable Protocol 20 JavaScript SDK releases.