Blog Article
Protocol 19 Upgrade Guide
Author
Justin Rice
Publishing date
The Stellar Protocol 19 upgrade vote is scheduled for June 8, 2022. To prepare, make sure to install up-to-date versions of all your Stellar-related software — including Stellar Core, Horizon, and any Stellar SDKs you use — in advance of that date. Network upgrades are immediate when validators accept a new protocol version.
All new releases work with the current protocol, so you can install updates as soon as they're available. If you have any questions, make sure to ask them on the #protocol-19 channel on the Stellar Developer Discord, which is where the ecosystem is coordinating and sharing information about the upgrade.
Key dates
- April 26: Stellar Core released
- May 2: Horizon released
- May 9, 1500 UTC — Testnet upgraded
- June 8, 1500 UTC — Public network upgrade vote
Protocol 19 Releases
We've gathered a list of software that needs updating below. Please make sure to check release notes for specific instructions and requirements.
Stellar infrastructure
Node operators need to install the latest version of Stellar Core and Horizon. For setup-specific details, see the sections below.
SDKs
For developers, links to the relevant release page are here. The minimum release required to support Protocol 19 is listed in parentheses, but as always, we encourage you to keep your integration up to date by installing the latest release. We will continue to update this list as new releases come out.
If you run Stellar Core
Upgrade to Stellar Core v19.1.0, which includes support for Protocol 19. If your node is running a pre-19 version of Stellar Core when the network upgrades, it will immediately throw an error and lose sync.
You should also make sure to take a look at your quorum set configuration, which may need adjusting due to recent changes in network topology. For inspiration, check out the SDF quorum set configuration, which lists the current Tier-1 validators.
If your node is a validator, you can arm it to vote for the public network upgrade with the following command: upgrades?mode=set&upgradetime=2022-06-08T15:00:00Z&protocolversion=19
For more information, see the Upgrading the Network doc. To stay in the loop as we coordinate that vote, join the stellar.public #validators channel on the Stellar Developer Discord.
If you run Horizon
Upgrade to Horizon v2.18.0, which has full support for Protocol 19. If you are running a pre-v2.17.0 version of Horizon when the network upgrades, it will break as soon as it tries to ingest one of the new transaction preconditions or signature types.
Upgrading also involves a database migration, which is described in the Horizon CHANGELOG. It should execute pretty quickly because it adds columns that correspond to new account extensions and transaction preconditions introduced in Protocol 19, so it doesn't involve any backfilling.
By default, v2.17.0 runs a mini-Stellar Core (aka Captive Core) as a subprocess of Horizon, so you don't need to run a standalone Stellar Core node. While we advise everyone who runs Horizon to deploy the Captive Core architecture, we also understand that some people still rely on legacy architecture and run Horizon along with a standalone Stellar Core node. If that's the case for you, and you would like to keep it that way, you can disable Captive Core by setting ENABLE_CAPTIVE_CORE_INGESTION="false" env variable.
After upgrading to the new version of Horizon, Horizon operators also need to upgrade Stellar Core to v19.1.0. That's true even if you run the Captive Core architecture since Horizon uses whatever Stellar Core package you have installed. Also note that this version fixes an issue with an earlier version of Core that prevented Captive Core nodes from applying certain ledgers, so if that's happening to you, make sure to upgrade to v19.0.1.
Please also make sure to take look at your quorum set configuration, which may need adjusting due to recent changes in network topology. Follow instructions for configuring Captive Core, and take a look at the SDF quorum set configuration for a list of the current Tier-1 validators.
If you have a custom Stellar integration
If you're using Stellar but you're not using a Stellar SDK, you will likely need to manually update your code. You may want to check out the Python SDK issue that outlines the changes necessary to adapt to Protocol 19.
Also, please contact me and let me know everything you can about your custom integration. I'd love to find out more so we do a better job of informing, assisting, and accommodating people like you: [email protected].
Key Changes
Protocol 19 implements two Core Advancement Proposals, both of which facilitate the creation of payment channels and bridging solutions. CAP-21 adds new transaction pre-conditions. CAP-40 adds a new type of signer. For a high-level explanation of the kinds of things those changes allow you to build, see the Announcing Protocol 19 post. For an inventory of the changes, check out:
The first summarizes the Protocol 19 CAPS and details changes to the Horizon API and the Stellar SDKs; the second is designed to help SDK maintainers implement those changes. If you walk through them carefully, you should be able to understand what's coming.
Generally, though,installing up-to-date versions of any and all Stellar SDKs you use(along with Stellar Core and Horizon if you run a node) is sufficient for a smooth transition to Protocol 19.