Protocol 18 Upgrade Guide

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

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.

• Stellar Core v18.1.0
• Horizon v2.10.0
  

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.

• Javascript SDK v9.0.1
• Javascript Base v6.0.4
• Java SDK v0.29.0‍
• Go SDK v8.0.0‍
• Python v5.0.0‍
• iOS v2.0.4‍
• C# .NET v7.2‍
• Flutter v1.2.3‍
• Ruby v0.30.0

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: upgrades?mode=set&upgradetime=2021-11-03T15:00:00Z&protocolversion=18

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:

1. The Horizon Liquidity Pool API spec, which we shared in August, includes a "BREAKING API CHANGE" label for each breaking change, and bolds the relevant change in the JSON response.
2. The Javascript SDK v9.0.0-beta release notes has a "Breaking Changes" section, which includes a bulleted list that briefly describes each change.
   

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:

• Protocol 18 introduces liquidity pools. These are new objects with new associated elements, and they show up in a few places in API responses. There are also two new operations — one that allows users to deposit into liquidity pools; one that allows them to withdraw from liquidity pools.
• Protocol 18 increases trade price precision. This leads to type changes, and can cause potential precision issues downstream.
• Protocol 18 changes the XDR. If you update your SDK, you should be fine, but older versions of the SDKs will not parse XDR containing changed elements. If you use a custom XDR parser, you will need to update it to handle the XDR changes.
  

Specifically, Protocol 18 introduces the following changes:

New asset type

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.

New trustline responses

Clients tracking trustlines need to handle new possible responses. Specifically:

• Change trust on liquidity_pool_shares type has a different response shape.
• Trustline effects on liquidity_pool_shares type are missing fields.
• Sponsorship of a pool shares trustline has a different response shape.

New balance type

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).

Orderbook trade price type change + new liquidity pool trade

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:

• Offer ids are missing
• There's only one account present; the other side of the trade is a liquidity pool
  

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.

Trade aggregations change

Protocol 18 represents trade aggregations as strings in Horizon for consistency with liquidity pools, a consequence of the trade type change above.

XDR changes

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:

• Path payment (strict) results type changed (ClaimOfferAtom -> ClaimAtom)
• Manage buy/sell result type changed (ClaimOfferAtom -> ClaimAtom)
• ChangeTrustOperationResponse asset details changed (can be a liquidity pool asset)

‍