> Developers Blog

Protocol 18 Upgrade Guide

For the past few months, there's been growing excitement about the Stellar Protocol 18 release, which enables the creation of Automated Market Makers (AMMs) on Stellar.  In previous blog posts, we explained how AMMs can help improve overall network liquidity, talked a bit about how they will work on Stellar, and examined how the ecosystem is collaborating to prepare for their arrival.  Recently, we also added a liquidity pools Glossary entry to the Stellar docs that includes code examples and complete information about the new Protocol 18 operations. The goal of this blog post is a bit more nuts-and-bolts than any of those: it's to help you, dear business or developer building on Stellar, prepare for the upgrade. 

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 18, 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

  • October 6, 2021, 1500 UTC — Testnet upgraded
  • November 3, 2021, 1500 UTC — Public network upgrade vote

Protocol 18 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 Horizon. For setup-specific details, see the sections below.

As we mentioned in a previous announcement, if you are installing Stellar infrastructure from Debian packages, please make sure you are running Ubuntu 18.04 or 20.04.  SDF is committed to supporting all Ubuntu LTS releases in order to ensure that we stay in alignment with Ubuntu, which should make it easier to plan ahead, and to maintain secure and stable Stellar infrastructure.  As part of that commitment, we no longer build packages for deprecated versions of Ubuntu, such as 16.04 (Xenial).  If you're running a non-LTS version of Ubuntu, please factor in some extra time to update your infrastructure.

SDKs

For developers, links to most recent SDK versions are here.  In general, you should always install the most recent SDK release. We will continue to update this list as new releases come out.

If you run Horizon

Upgrade to Horizon v2.9.0, which has full support for Protocol 18. If you are running a pre-v2.9.0 version of Horizon when the network upgrades, your Horizon instance will not be able to ingest or query liquidity pool ledger entries or operations, and will crash when it encounters one. 

Upgrading from a version <= v2.8.3 will trigger a state rebuild, which will likely take 10-15 minutes. During the rebuild, Horizon will not ingest new ledgers, so you may experience a brief amount of downtime.

By default, v2.9.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 the {% code-line %} ENABLE_CAPTIVE_CORE_INGESTION="false"{% code-line-end %} env variable. 

Horizon operators also need to upgrade Stellar Core to v18.0.3. That's true even if you run the Captive Core architecture since Horizon uses whatever Stellar Core package you have installed. 

If you run Stellar Core

Upgrade to Stellar Core v18.0.3.  If your node is running a pre-18 version of Stellar Core when the network upgrades, it will throw an error and lose sync.  We have discovered and patched a few issues over the past few weeks, so please check the release page and make sure to upgrade to the latest version of Stellar Core.

If your node is a validator, you can arm your it to vote for the upgrade with the following command: {% code-line %} upgrades?mode=set&upgradetime=2021-11-03T15:00:00Z&protocolversion=18{% code-line-end %}

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 Java SDK issue that outlines the changes necessary to adapt to Protocol 18.

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]


Subscribe to developer updates

Thank you for subscribing! Please check your inbox to confirm your email address.

There was an error. Please try again.

More articles

News and insights for developers