An Introduction to Stellar Smart Contract Development

April 1, 2019

With the term smart contracts we usually define computer programs that are executed by a distributed computer. This is the case, for example, of Ethereum smart contracts, built using the Solidity programming language. While targeting a Turing-complete virtual machine empowers programmers to build exceptionally complex contracts, it also increases the possibility of bugs that result in the loss of millions of dollars.

Stellar takes a different approach to smart contracts. Contracts are built by composing transactions together and taking advantage of the following features:

While this limits what it’s possible to build on top of Stellar smart contracts, it also results in contracts that are more safe from unexpected bugs. As we will see later in this post, it is possible to model smart contracts as state machines, resulting in contracts that are easier to verify and test.

Use case: Escrow service

One of the most simple use cases is an escrow account, where the account will hold the funds for a predetermined amount of time, only after this time has elapsed the funds can be transferred. You can read more about escrow accounts on the Stellar official documentation.

In this implementation of the escrow account, the funds are not transferred between accounts, instead it’s the ownership of the escrow account that changes. In the beginning the escrow account is shared between the two accounts (the payer and payee). After the predetermined time has elapsed, the payee can submit a transaction to change the ownership of the escrow account to themselves. If this does not happen within a prearranged time frame, the payer account can recover the funds in a similar manner.

Escrow contract transactions
Escrow Contract Transactions

Ownership of the account is changed by submitting an operation to change the signer of the account.

Smart contracts as Finite State Machines

The previously discussed implementation of an escrow account works correctly but has the following downsides:

  1. The users can inadvertently bump the escrow sequence number, invalidating the previously signed transactions,
  2. The contract flow is not obvious when looking at the contract in a viewer (e.g. StellarExpert).

In this section we propose a method to build Stellar Smart Contracts that solves both of these problems.

Stellar includes a mechanism for adding pre-authorized transactions to an account. We can use them to build state machine based smart contracts, where the account states are also the machine states, and edges are represented by pre-authorized transactions. The objective of each transaction then becomes:

  1. Change the state of the contract, for example by moving around funds,
  2. Setup the state transitions from the next state.

As an example, let’s revisit the escrow smart contract of the previous section.

The state machine diagram for this contract is the following:

Escrow State Machine
Escrow State Machine

where the states are as follows:

The transactions are as follows:

Transaction #0
Payer Account

Transaction #1
Source: Escrow Account

Transaction #2
Source: Escrow Account
Time Bounds: Minimum Date: Unlock Date

Transaction #3
Source: Escrow Account
Time Bounds: Maximum Date: Recovery Date


In this post we discussed the basic of Stellar Smart Contracts and how to implement an escrow account with them. We then formalized a way to build smart contracts using state machines and the benefits of this method.

Power up your wallet.
Start tacking back control on your crypto transactions. Join LockerX and create your first smart contract in minutes.
Start for free Now