Simple Escrow Contract using Stellar

Sylvain Faucherand
Aug 26, 2018 · 4 min read

This post is a follow-up of a previous one, where I experiment with a simple XLM transaction: First impressions at creating Stellar Smart Contracts.

Émile-Antoine Bayard’s Illustrations for Around the Moon by Jules Verne (1870)

One common example of Stellar Smart Contracts is how to create an escrow. This is what I’ll describe below. I’m well aware that examples on the website are neatly explained as well, my point here is more to give another newbie introduction, using a newbie language.

Here is the scenario we’ll follow, where we want both (A)lice and (B)ob’s signatures to release funds from an escrow account:

  • Alice creates and funds an Escrow account
  • Alice creates an Escrow disbursement transaction to Bob’s account
  • Later on, Alice signs the Escrow disbursement transaction
  • Finally, Bob signs the disbursement transaction and submits it to receive the funds

We’ll consider that Alice and Bob’s accounts already exists in the Stellar network. You can refer to my previous article to see how this can be done with the Stellar testnet.

Bear with me, these steps can be simplified a lot. But I chose to separate each of them to make the reasoning clearer, hopefully.

Alice creates an Escrow Account

Alice uses her account to create a new account (the escrow) and fund it. The choice of 2.5 Lumens comes from the fact that a Stellar Account needs a minimum balance of 0.5 XLM, as specified in the doc. We’ll see afterward why 2 more Lumens are added.

Once built, the Escrow account creation transaction is submitted to the network.

Escrow account configuration (multisig)

We want to constrain the disbursements from the Escrow account such as both Alice and Bob’s signatures are required. This is done by changing the Escrow account’s properties.

This is a key point to realise: you need to set options on the Escrow account to apply these constraints.

In the threshold properties, by giving the masterWeight a value of 0, we prevent the Escrow account private key to be used to sign any transaction in the future.

You’ll see the signer’s weights are set to 1 each. Hence the threshold needed to perform any transaction set to 2: one for Alice, one for Bob (zero for the Escrow).

Thus, both Bob and Alice will need to sign transactions from the Escrow account once this modification has been submitted to the Stellar network.

This modification is also valid because the Escrow account has been funded with enough Lumens (2.5): 1 per signer + 0.5 minimum balance.

Alice sends Lumens to the Escrow account

This could have been done when Alice created the Escrow account. However, I’ve isolated this transaction for the sake of clarity.

Create the escrow disbursement transaction

This transaction only specifies the payment from the Escrow account to Bob’s.

For this transaction to be signed by both parties, and trigger the payment to Bob, it has to be possible to send it over. But the Stellar network only validates transactions signed by all signers.

Creating a transaction doesn’t mean it has to be submitted to the network. After all, when you use the Stellar JS SDK, a transaction is only an in-memory JS object before you eventually submit it via the SDK’s submitTransaction() method.

Fortunately, Stellar uses a format you can use to exchange transactions: XDR. That is the reason why the following script can serialize this transaction and save it as a file.

In most examples in the docs, you’ll see Alice and Bob’s signature executed in the same script. But in a real-world use-case, you’ll hardly have access to Alice and Bob’s private keys at the same time, or even on the same device… If so you may have a big problem.

Later on…

Alice signs the escrow disbursement transaction

The transaction can be deserialized and signed by Alice with her account‘s private key then serialized again, which makes it half-signed so far.

Bob signs and submits the transaction

Now, Bob’s private key can be used to sign the transaction as well, and being signed by all signers, it can be submitted to the network.

There you go: Bob’s account should be credited with the funds in the next 5 seconds.

I hope this demonstration will help you start with your own use cases, and reveal how Stellar can be a very good bet for smart contracts implementations.

You’ll also find a few videos I released on this channel:

Update (20/08/2019): update code sample following sdk updates, add link to videos


Coinmonks is a non-profit Crypto educational publication. Follow us on Twitter @coinmonks Our other project —

Sylvain Faucherand

Written by



Coinmonks is a non-profit Crypto educational publication. Follow us on Twitter @coinmonks Our other project —

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade