Blog Article

Protocol 13 Improvements


Justin Rice

Publishing date

Protocol upgrade

A few times a year, we roll out a major upgrade to Stellar Core, and it has cascading effects that require people throughout the Stellar ecosystem to update their software. You may have noticed our Guide to Protocol 13 Prep that came out a few weeks ago, or a series of announcements I've made on pretty much every Stellar-related channel since then.

If you run Stellar Core or Horizon, use a Stellar SDK, or have a custom Stellar integration, you need to make sure your software supports Protocol 13 between now and June 18, which is when the public network validators will vote on whether to upgrade the network as a whole. Note: that's two weeks later than the original vote date. We wanted to give people a bit more time to prepare

Why the major upgrades? The Stellar protocol is designed to evolve to meet the needs of network participants and to drive technology forward into new territory. Major releases are our chance to introduce new features and crucial optimizations that require breaking changes — changes that make prior releases incompatible and obsolete — and the widespread effort required is worth it to make necessary progress and address new and ongoing needs of the ecosystem.

  • Protocol 11 changed the way fees work and the way network capacity is measured.
  • Protocol 12 ended inflation and introduced a new kind of path payment.
  • Protocol 13 adds three new features: fee bumps, fine-grained control of asset authorization, and first-class multiplexed accounts.

Every new feature added to Stellar Core is introduced as a separate Core Advancement Proposal, and in this post, we'll walk through the Protocol 13 changes, explain why they matter, and link to the relevant CAPs for those who are interested in digging deeper.

Fee bumps (CAP15)

Fee bump transactions allow you to pay the fee for an existing transaction without having to re-sign the existing transaction or manage sequence numbers. We'll get into the nitty gritty of how they work in a forthcoming technical blog post — so stay tuned for that — but for now, let's stick to a simple question: why are fee bumps useful?

Fee bumps allow apps to cover user fees

First, fee bumps make it easy to pay a fee on behalf of another account. A non-custodial wallet, for instance, can cover a user's transaction fees without controlling the user's account. Prior to Protocol 13, the wallet could attempt to cover fees by sending funds directly to the user, but there was no guarantee that the user would actually spend those funds on fees, and there was no way to recover unspent funds. Unwitting users could wedge their accounts by locking funds intended for fees into a buy order; malicious users could attempt to actively cull funds intended for fees into ill-gotten gains.

Pre-Protocol-13, the wallet could also attempt to use its own account as the source account for user transactions, but if it's doing that for scores of users, it's impossible to ensure that transactions are submitted in the correct order. It's a sequence number management nightmare.

With fee bumps, wallets can cover fees without relying on sequence number magic, and without having to explain things like surge pricing to users. That means they can conceal the finer details of the network and its requirements, which allows them to create a simpler product that appeals to a wider user base.

Fee bumps allow you to increase fees for pre-signed transactions

The second way fee bumps are useful: they allow you to increase the fee for a pre-signed transaction. If you create and sign a transaction intending to submit it on a future date — say you're putting funds in escrow — you count on the network continuing to exist in a state that will allow you to execute that transaction. If, when you go to submit the transaction, the fee it specifies is too low — which can happen if the network is in surge pricing mode, or the network minimum has increased — you won't be able to get it on the ledger. In these situations, it might not even be possible to recreate the transaction: the signers could be unavailable or unwilling to agree to the old terms; the signing key could be lost. Your funds could get locked in escrow forever.

Fee bumps give validators the flexibility to increase fees

By preventing pre-signed transactions from failing due to insufficient fees, fee bumps pave the way for a potential change hinted at in the paragraph above: now validators can, if necessary, raise the minimum network fee.

Fees are an important tool for dealing with network spam, and like all crucial network settings, minimum fees are determined by validator vote. Giving validators the flexibility to change fees to keep network costs aligned with actual network usage and fluctuating XLM prices is crucial to the continued high functioning of Stellar. Should validators deem it essential to increase minimum fees, they can now do so without locking anyone's funds in escrow.

Fine-grained control of asset authorization (CAP-18)

Stellar has always had protocol-level asset authorization that's incredibly easy to use: you can set an asset to require authorization, and you can make authorization revocable so you can turn it on and off as necessary. You do both those things by setting simple account-level flags.

However, when you turn off authorization for a given account, you also cancel all buy and sell orders that account has for the asset in question. Protocol 13 introduces a new flag that allows you to revoke authorization while maintaining orders on the books, which makes it easier to tokenize regulated assets like securities.

Often, issuers of regulated assets want customers to be able to trade their assets, but they also need to exert a high level of control over who can hold them, how much they can hold, and under what conditions they can sell or buy more. With fine-grained asset control, an issuer of a regulated asset can set the asset to require the new kind of authorization — the one that keeps orders on the books — and when a user wants to make a payment or new offer, the issuer can check to see if it's allowed given regulations. If it is, the issuer sandwiches three operations into a single transaction:

  1. Authorize the account to use the asset (an operation the issuer signs)
  2. Make the payment or offer (an operation the user signs)
  3. Deauthorize the account to use the asset. (an operation the user signs)

Because transactions on Stellar are atomic, all three operations happen in one fell swoop, and the issuer ends up approving a single, specific operation. Issuers can condition approval on a compliance check, so they can keep payments and offers within the bounds of regulations.

First-class multiplexed accounts (CAP-27)

Protocol 13 also introduces a new type of account address that includes a built-in 64-bit memo. This change is important for exchanges and other custodial services that maintain a single deposit Stellar address and require memos in order to properly route payments to the correct user account in their internal databases. With these new multiplexed accounts — muxed accounts for short — custodial services can give each user their own account ID that routes to the underlying exchange Stellar address.

In addition to making it impossible for users to forget required memos (a problem we came up with a temporary solution to recently), muxed accounts are robust against typos, which current memos are not. They also allow you to apply memo-like functionality at the operation level, so you can bundle multiple payment operations to multiple muxed accounts into a single transaction, which is cleaner, more efficient, and better for the network than submitting transactions made of single payment operations.

And while memos can let you know which sub-account a payment should go to, they can't let you know which sub-account a payment came from. When a payment from a sub-account needs to be returned, for instance, there’s no way to navigate the last mile: the return may get to the custodial service, but they don't know whose account to credit. By making it possible to identify the sending sub-account, muxed accounts make those kinds of returns easy.

The thing about the muxed accounts, however, is that while they're baked into Protocol 13, they're not actually accessible as of this writing. We put in the wiring, but haven't added a switch. Before muxed accounts are ready to use, we have to figure out the best way to expose them in Horizon and the Stellar SDKs, and that's going to take some thought, testing, and validation. There's a proposal for how to do it — SEP-23 — and an ongoing discussion on Github. If you want to see how it all shakes out — or you have any thoughts about the best path forward — please join the discussion!

Protocol optimizations

In addition to the three new features above, Protocol 13 also includes two optimizations that make the network run a little better.

CAP-28 introduces a small improvement in convenience when dealing with pre-auth signers.

CAP-30 stops checking for whether the issuing account for an asset exists during payment, path payment, and placing/managing an offer.

Those two optimizations don't have the same obvious impact on most users as fee bumps, better control of asset authorization, and multiplexed accounts, but they do help Stellar Core, — and therefore the network as a whole — run a little leaner.

What's next?

All the Protocol 13 changes have been merged and released in Stellar Core v13.0.0, and the testnet is already running on Protocol 13. For the public network to upgrade, validators will need to arm their nodes to opt for Protocol 13, which they do using the following command:


If enough validators arm their nodes to upgrade, the network will immediately switch over to Protocol 13, and all the new features will be accessible to anyone who uses Stellar. When that happens, it's important that you're running compatible software: Stellar Core, Horizon, and Stellar SDKs that don't support Protocol 13 will cease to function properly, and your product, app, or service will likely break. At least until you install new software.

To find out more about what you need to do to upgrade, check out our Guide to Protocol 13 Prep.