Building applications that listen for Stellar payments

Ace Subido
Jul 3, 2018 · 4 min read

A main feature of the website was to display payments made by a participant to any of our deposit addresses.

Image for post
Image for post

We first display an address, and a memo they can use when sending a payment.

A memo on a Stellar payment is used to “tag” that transaction. Memos are meant to semi-identify the person/entity making the payment, outside the blockchain’s context. They’re useful when viewing payments made to an address, you’ll know which transactions came from who.

Once a payment is sent with the memo, displaying payments on the relevant user’s dashboard should be fast. Stellar transactions are quick. It will be uncharacteristic of our application if users wait more than a minute to see transactions reflect on the website. To display payments, we’ll need to make our application “listen” on Stellar.

Listening for Payments

Image for post
Image for post

With Horizon, getting the list of payments on an account every X seconds or minutes might be the easiest method to listen for payments.

Although, instead of polling, Horizon has an option that allows us to achieve “instant display”. We can stream payments for a specific account if we add the text/event-stream request header when getting the list of payments from an account.

Writing the code to accept the stream, handling failures, and keeping tabs of the cursor would take effort, but it’s not without its rewards. You keep your application simple, apart from the Horizon dependency.

Another option beyond writing code would be to use Stellar’s Bridge Server. You can run it on your own servers, and configure it to listen for payments to an address. Once a payment is made to an address it makes an HTTP POST , a callback, to an HTTP endpoint of your configuration.

Protecting the callbacks endpoint

This allows for potential abuse. You risk enabling bots or people to post fake transactions of any kind to that endpoint. Your application might get confused with what is from the blockchain and what is fake.

With this in mind, it means we’ll have to think of ways to secure this endpoint. When mulling about security, it’s good to think in layers.

Image for post
Image for post
“Defense In Depth” - a layered approach to security, sometimes dubbed as the “Onion” model.

Should you put more logic on the application layer? Should we enforce stricter record uniqueness on the database layer? What about options in restricting access via the network layer? How about validating authenticity of application-related payloads against another node in the blockchain?

Here are some thoughts on securing the callback endpoint:

1. Make the application a “smart listener”

Once a transaction is “listened” and “recorded” by an application, it should keep tabs of it. Transactions on the Stellar blockchain are immutable, so we shouldn’t think about tailoring code to expect changes. If the application, or your callback endpoint, receives a transaction of the same ID, it shouldn’t recreate it. This sort of behavior is called “idempotence”.

Make the code on the callback endpoint “idempotent”.

2. Configure Stellar Bridge Server to use a mac_key

3. Validate callback authenticity by checking callbacks against a Horizon server

Though highly unlikely to happen, it is still important to mitigate this risk. One way to circumvent an impersonating bridge server is to check an incoming callback against the Stellar blockchain. You can query another Horizon instance, check if the incoming payload actually exists and compare if they have the same contents (amount, source address, memo, asset_type, etc.)

Displaying blockchain payments on an application might be a simple task, but it’s worth thinking how your applications should securely listen to the blockchain. I hope this post has inspired you to think about security when building blockchain-based applications, even ones that simply read from it.

If you’re using Rails to build an application that listens for Stellar payments, we built a rails engine that makes Rails apps securely listen for callbacks coming from a Stellar Bridge server.


Transforming money services with cryptocurrencies

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store