Blog Article

Multisig and Simple Contracts on Stellar


Stellar Development Foundation

Publishing date


As many of you know, the team at SDF has spent the past several months writing code for an upgraded distributed network. It's finally ready to use!

I'm not sure I can adequately express how excited I am that Stellar is moving to this codebase, but I'll try. It feels like...running free through a sun-soaked dewy field of red clover with hedgehogs, or maybe emerging from my cocoon as some sort of butterfly dragon.

More importantly, it means that the platform is truly ready for developers to build the world's new financial services. In this post, I'll highlight some of the benefits and features of the upgraded network, and then give an example of something you might build with these features.

So, what's different?

The upgraded Stellar network is more secure, scalable, and modular than the old codebase. The Stellar Consensus Protocol (SCP) optimizes for safety rather than liveness when the network loses quorum—meaning the system is secure against forking.

The Stellar Core code is now more comprehensible and elegant. Less than half the size of the previous codebase, it runs faster and uses less memory and disk space. (The upgraded Core code handles only consensus, while Horizon, the API server, handles pathfinding and provides a web-based interface to Stellar Core.) It also keeps data in more obvious and simple formats, in safer places. For example, the codebase performs continuous backup to off-validator storage in XDR, an Internet-standard format. And the live ledger is in a conventional SQL database.

New Features: Batching and Multisig

There are a lot of great things about the new code, but I'll address two features in more detail: batching operations and multisignature accounts.

On the upgraded network, transactions are batched in a chain of operations. In each batch, all the operations will either succeed or fail. Operations in the same batch can even be from different accounts. For example, you can create a transaction where accountA sends to accountB if and only if accountB sends to accountC. In this case, the transaction would require the signatures of both accountA and accountB.

Not only can transactions be signed with multiple keys, but accounts can have multiple signers. Multisig adds flexibility in securing particular Stellar accounts and managing who has access to them. You can assign each signer a different weight, and each operation has a threshold. With this design, you can easily set up m of n schemes. For example, you might manage a multisig account so that transactions can be validated either by one person alone or by all three of these other people.

This design opens up all kinds of possibilities. Together, for example, batching and multisig allow you to make what we call simple contracts. Simple contracts enforce certain constraints regarding 1) who must approve a particular change in the ledger and/or 2) what changes must all occur together. And they enforce those constraints without the use of scripting.

Read a bit more about operations and multisig to get a better sense of how they might work together, or dive right into the example below.

Simple Contracts Example: Joint Crowdfunding

The city of Johannesburg needs a new hospital. The city government and an NGO are each willing to contribute $1 million to its construction, but the expenses total $3 million. Together, the two organizations want to crowdfund the missing million and to ensure that every dollar raised goes towards building the hospital. They also want to guarantee donors that, if the total isn't raised by March 2016, they will refund all donor money.

The Johannesburg city government and the NGO make a holdingAccount. This account collects the funds and, after March 2016, ensures that donors get their funds back if the funding goal isn't met. The holdingAccount is set to require both the government and NGO's keys as signers to authorize any transaction.

The city government sends $1M to the holdingAccount. NGO sends $1M to the holdingAccount. The joint party then creates the following transactions:


Sequence Number: N+1

Signers: Government & NGO This transaction is submitted to the network and the sell order ID is recorded for transaction3.


Manage Offer: create an offer to sell $1M participation tokens issued by holdingAccount for $1 per token.


Sequence Number: N+2

Time Bounds: valid from 1st March 2016 till...

Signers: Government & NGO


Payment: send $3M to contractorAccount.


Sequence Number: N+3

Signers: Government & NGO


Manage Offer: cancel the sell offer created in transaction1.

Payment: send $1M to Government

Payment: send $1M to NGO.

Manage Offer: create an offer to buy 1M participation tokens for $1 per token.

Transactions 2 and 3 are published but not submitted to the Stellar network. Anyone can submit them to the network later, but they won't be valid until March 1, 2016. Also, because of the sequence number, transaction2 must occur before transaction3.

If you want to donate to fund the hospital you must do the following:

  1. Create a trustline to the holdingAccount for participation tokens.
  2. Buy participation tokens by creating your own offer. Your account will receive tokens and the holding account will receive dollars.
  3. If an additional $1M is raised by March 1st, the money will be sent to the contractor via transaction2, OR
  4. If the funding goal is not met, transaction2 will fail and transaction3 will complete.
  5. If transaction3 completes, you can retrieve your donation by selling your participation tokens back to the holdingAccount. The parameters of this setup are flexible. There are many possible modifications, including extending the design to pay out to individual recipients or to pay the contractor over time.

Into the Future

Seamless crowdfunding with multiple major stakeholders—and without fees—is just one example of what's possible with batching and multisig on the upgraded Stellar network. My hope is that it sparks other ideas: subscriptions, escrow, group savings accounts and health savings accounts, a lightning network, farm subsidies, ability to charge back, and even games (I almost got tic-tac-toe working for this example but ran out of time). I'm excited to see what people build!