Federated Stellar addresses

A few days ago a nonprofit foundation, partly backed by Stripe, launched a new decentralized payment network (similar to Bitcoin) called Stellar. Unlike with Bitcoins Stellar doesn’t get mined (so maybe the vast amount of computing power of all this mining hardware could get used to sequence DNA or run SETI@home in the future) and Stellar supports transactions in arbitrary currencies via so called gateways. To learn more about Stellar, their launch blog post and Stripe’s blog post is probably a good starting point.

Another interesting feature of Stellar is federation.

What federation is about

Each Stellar user has both a wallet address (similar to Bitcoin) as well as a human readable username for that address (which is quite handy as sending a payment to e.g. watsi is a lot easier than sending one to gN4oHfh4iLRCSsrHVxVHzt6rZXs6EyTCe4). What’s nice about these usernames is that they are actually federated addresses and not just usernames. The username watsi is just the short version of watsi@stellar.org.

Stellars federation protocol makes it possible to set up federated addresses for your domain. That means, that if you control the domain example.org, you could receive payments under e.g. john.doe@example.org. Think about it like some kind of domain name system for wallet addresses. Stripe’s CTO Greg wrote a blog post with some more details about how federation works and also provides a link to his sample federation server there.

How a client figures out the recipients wallet address

Just to give you a rough idea, here’s a quick overview of how a Stellar client figures out the recipients wallet address.

Locate and parse stellar.txt

When you are trying to send Stellar to e.g. john.doe@example.org the client first tries to find a file called stellar.txt for the example.org domain by trying the following URLs in this order:

• https://stellar.example.org/stellar.txt
• https://example.org/stellar.txt
• https://www.example.org/stellar.txt

If the file is found, the client parses it for the URL of the federation server that’s responsible for this domain. For this example the contents of that file might look something like this:

[federation_url]
https://federation-server.example.org

Query federation server

Now the client makes it’s final request and asks the responsible federation server for the wallet address of john.doe@example.org. If everything worked out as expected and the federation server actually knew that user, the client now knows the wallet address for john.doe@example.org and is able to send a payment.

Running your own federation server

To run your own federation server you’ll need a valid SSL certificate for both the server where your stellar.txt file is located as well as for the domain your federation server itself is running on (those two could of course be the same). If you are also curious about Stellar federation you can give my implementation (it’s on GitHub) a try.

Disclaimer

A quick word of warning: I put this together for fun and haven’t spent a lot of time with it, so please use it at your own risk and don’t sue me if you end up sending your life savings to /dev/null. :) The federation protocol itself also still seems to be evolving, so things might break when they change the protocol.

Let me know if you find bugs or have suggestions for improvement.

Any comments? Ping me on Twitter. 👉🏻 Get my newsletter for occasional updates. ✌🏻