Understanding Stellar Path Payments
One of Stellar’s most unique features is the Path Payment. Path Payments allow users to send an asset and have it converted into a different asset before arriving at its destination. I send dollars; you receive euros.
For those who are curious, this post will explain what goes on behind the scenes to make path payments work. I’ll assume you’re familiar with concepts like trustlines, the Stellar decentralized exchange (SDEX), and Stellar assets.
Why are path payments useful?
Path payments allow a user to send an asset they already hold, and to convert it in transit into an asset a recipient wants to receive. Since the conversion is built into the operation, the sender never needs to touch the destination asset: they can keep a balance in their favored currency, and instantly transact with anyone anywhere in any currency.
Imagine someone in the U.S. — whose account can only hold dollars — wants to send money to a friend in Europe — whose account can only hold euros. In a path-payments-less world, the sender would create a trustline for the euros, check some market orders on the SDEX for converting dollars to euros, find the best rate, submit a buy order, and then send the euros to their friend. It would take some time and effort, and the sender would have to pay fees three times.
Path payment operations simplify the process by eliminating the need for the sender to have a trustline, and by bundling transfer and conversion into a single operation that incurs a single fee. This reduces the overhead and complexity involved in navigating trustlines and the SDEX, and allows a user to easily take advantage of the multiplicity of Stellar assets.
Path Payment Strict Send & Strict Receive
There are actually two path payment operations as of Stellar-core v12 — path payment strict send and path payment strict receive.
Path payment strict send allows you to specify the amount of an asset you’re willing to send. The amount received will vary based on order book offers. You can also specify a destination minimum, so you can set a lower bound for acceptable conversion to protect against bad rates. For example: I can afford to send my family a max of 50 USD/month; I’d like to send exactly that much, whatever that ends up being in NGN.
Path payment strict receive is basically the opposite: it allows you to specify the amount of the destination asset that will be received. The amount sent will vary, though you can still specify a maximum amount you’re willing to send. The scenario here: I’m renting an apartment in Paris, and it has a 150 EUR booking fee; I want to make sure the landlord receives exactly that amount, whatever that ends up being in USD.
Finding a Path
Before diving in to the payment itself, it’s important to understand what a path consists of. A path is a trade, or chain of trades, that takes offers that exist on an SDEX order book. An order book is a list of buy and sell offers for a particular asset pair. Check it out:
When you make a path payment, the first thing your wallet does in the background is query Horizon, the Stellar-network API, to find all the possible paths. Horizon checks your Stellar account for balances and trustlines, and returns paths from the asset you’re sending to the destination asset. These paths will come in the form of USD → XLM → EUR or USD → BTC → CNY → XLM → EUR. Paths can contain up to six “hops” between assets.
A path search can return several options, and most services pick the path that offers the best conversion rate. For example, even though USD → XLM → EUR may be the shortest path by number of hops, it’s totally possible for USD → BTC → CNY → XLM → EUR to be the cheapest path, and in most circumstances, that’s the path you’d choose.
Executing the Path Payment
After your wallet finds the optimal path, it will construct a transaction around it and submit it to the network. The send amount is then debited from the source account and the destination amount is credited to the receiving account. This is the equivalent of a short-term, no-interest loan. After these two steps, the orders that constructed the path are filled to meet the buy and sell requirements of converting the asset that was sent. That is how the previously mentioned “loan” gets paid back!
One thing to note is that this set of steps is actually atomic, meaning everything happens instantaneously. If any part of the above process fails, then the entire transaction fails. Nothing gets credited or debited, and no orders get filled.
Example Path Payment
Let’s imagine a path payment from USD → XLM → EUR. Ignoring XLM for fees, we’ll assume that Person A has a balance of USD tokens and Person B has a balance of EUR tokens. Person A wants to send 2 EUR to Person B through a path payment strict receive. Person A’s wallet performs the path search, finds the optimal path, builds a transaction around that path, then submits the transaction to the network.
Here are the steps after the transaction is submitted to Stellar:
- Person B’s balance is credited +2 EUR
- Person A’s balance is debited -2.2 USD (based on the path exchange rate)
- Person A buys XLM for USD (taking an on offer in SDEX orderbook)
- Person A buys EUR for XLM (taking another offer in SDEX orderbook)
After filling the path of orders, Person A’s balance will now be 2.2 USD less, while Person B’s will be 2 EUR more.
The cool part is, all of that action is encapsulated in one operation and costs one fee!
🔥 Tip: You can also use path payments for other things such as trading. I mentioned earlier that path searches find the most optimal path from one asset to another. If you find yourself overwhelmed by order books you can simply send a path payment to yourself (from asset A to asset B) and this will have the same effect as making a trade.
If you’re interested in exploring path payments or using them yourself, the Keybase wallet has path payment functionality built in and documentation is also available here.
For any questions you may have head over to the public Stellar Keybase team or the Stellar Stack Exchange.
