An Introduction to Stellar Smart Contract Development

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:

  • Multisignature, Thresholds, and Key Weights We can specify what signature are required to change the state of an account
  • Batching Either all operations in a transaction succeed or none of them does
  • Sequence Transactions are processed only if their sequence number is increasing
  • Time Bounds Limit the time frame within which transactions can be accepted by the Stellar Network

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.

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:

where the states are as follows:

  • S0 Initial State. The account was created but is not funded.
  • S1 Account Funded. The account is funded and waiting for one of two transitions: the funds will be transferred to the payee or the payer.
  • S2 Account Merged with Payee account.
  • S3 Account Merged with Payer account.

The transactions are as follows:


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.

In the next posts we will use this framework to build more complex (and useful!) types of contracts. If you are interested in using Stellar Smart Contracts but don’t want to deal with the complexity, take a look at LockerBee!.

Originally published at