Blog Article
Protocol 17 Upgrade Guide
Author
Justin Rice
Publishing date
Protocol upgrade
Asset clawback
Regulation
It's time to get ready for the Stellar network upgrade to Protocol 17! This version of the protocol includes a new Asset Clawback feature that we've documented in detail and described at a high level in the Protocol 17 Improvements blog post, so check those out if you're interested in learning more. The goal of this guide is to share key dates and action items to help you prepare.
If you develop on Stellar, you need to install up-to-date versions of all Stellar-related software — including Stellar Core, Horizon, and any Stellar SDKs you use — in advance of the network upgrade. If and when validators vote to accept Protocol 17, the upgrade takes effect immediately, and since all the new software is backwards compatible with the current protocol, the best course of action is to update sooner than later. Doing so will ensure your Stellar integration keeps on ticking when the network levels up.
Key dates
- May 4, 2021 at 1500 UTC — Testnet upgraded. Now the testnet is running Protocol 17!
- June 1, 2021 at 1500 UTC — Public network upgrade vote
Protocol 17 Releases
We've gathered a list of software that requires updating below. Please make sure to check release notes for specific instructions and relevant details to ensure you understand all relevant requirements.
Stellar infrastructure
Node operators need to install the latest version of Stellar Core and/or Horizon. For setup-specific details, see the sections below.
SDKs
For developers, links to minimum SDK versions are here.
If you run Horizon
Upgrade to Horizon v2.3.0, which has full support for Protocol 17. If you are running a pre-v2.2.0 version of Horizon when the network upgrades, your Horizon instance will not be able to ingest or query asset clawback operations, and will crash when it encounters one.
By default, v2.3.0 deploys Horizon's new architecture. It 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, and you don't need to take any additional steps to update Stellar Core. Just upgrade to this version of Horizon, and you're good to go.
While we advise everyone who runs Horizon to deploy the new 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. In this case, you will also need to upgrade Stellar Core separately to v17.0.0.
If you run Stellar Core
Upgrade to Stellar Core v17.1.0. If your node is running a pre-17.0.0 version of Stellar Core when the network upgrades, it will throw an error and lose sync.
If your node is a validator, you can arm your it to vote for the upgrade with the following command: upgrades?mode=set&upgradetime=2021-06-01T15:00:00Z&protocolversion=17
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 Keybase.
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 JS SDK issue that outlines the changes necessary to adapt to Protocol 17.
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].