Stellar Development Foundation
Protocol 18 introduces breaking changes
So make sure to install up-to-date software, including SDKS
Before November 3, 2021
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.
Protocol 18 introduces breaking changes, so 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 November 3, 2021 upgrade vote. If validators vote to accept Protocol 18 on that date, the upgrade takes effect immediately, and since all the new software is 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.
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.
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.
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.
Upgrade to Horizon v2.10.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.10.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
ENABLE_CAPTIVE_CORE_INGESTION="false" 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.
Upgrade to Stellar Core v18.1.0. 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:
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'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].
Protocol 18 introduces breaking changes, and the goal of this section is to outline those changes in order to help developers understand what they need to do to prepare for the November 3 upgrade. Generally, the most important action to take: install up-to-date versions of any and all Stellar SDKs you use (along with Stellar Core and Horizon if you run a node). In many cases, updating your SDK is sufficient for a smooth transition to Protocol 18, but if you have questions, run into problems, or want a better understanding of what's going on under the hood, read on!
Two helpful resources to inventory the breaking changes:
You can consult those resources to understand what has changed in the Horizon API, and to see how those changes are reflected in Stellar SDKs. If you walk through them carefully, you should be able to understand what's coming. To make things easier, we will also summarize the changes in this doc. At a high level:
Specifically, Protocol 18 introduces the following changes:
In Protocol 18, asset_type can be liquidity_pool_shares. Previously the asset_type field was restricted to: native, credit_alphanum4, or credit_alphanum12. Clients hardcoded to expect only three types will experience issues.
Clients tracking trustlines need to handle new possible responses. Specifically:
Accounts can now have liquidity pool balances, which are different from asset balances. Devs who iterate over balances or present balances in UI need to account for the new types, or when a liquidity pool balance shows up for the first time in a user account that they parse, they may have issues (e.g. missing fields).
Protocol 18 introduces liquidity pool prices, which have type int64. Horizon represents these new prices as strings, and changes orderbook trade prices to strings as well, to be consistent with liquidity pools. Additionally, the deprecated offer_id field has been removed.
Protocol 18 also introduces a new type of liquidity pool trade. It differs from orderbook trades in that:
These price changes have precision implications: client calculations may continue to “work” even if they still store trade prices internally as int32s, but i) they might lose precision (likely just a few stroops here and there) or ii) some large price outside of int32 might show up and cause overflow. If your product or service uses price calculations, make sure to evaluate existing precision.
Protocol 18 represents trade aggregations as strings in Horizon for consistency with liquidity pools, a consequence of the trade type change above.
Clients need an updated parser to handle XDR changes. If you develop using a Stellar SDK, installing an up-to-date version of the SDK should do the trick. If you have a custom XDR parser, make sure you account for the fact that: