This tutorial gives an overview of the ideas behind Marlowe, as a domain-specific language embedded in Haskell. It also introduces commitments and timeouts, which are central to how Marlowe works in a blockchain context.
Programming Languages and Domain-Specific Languages¶
The first computers were programmed in “machine code”. Each kind of system had a different code, and these codes were low-level and inexpressive: programs were long sequences of very simple instructions, incomprehensible to anyone who had not written them. Nowadays we are able to use higher-level languages like C, Java and Haskell to program systems. The same languages can be used on widely different machines, and the structure of the programs reflects what they do. On blockchain, their equivalents are languages like Plutus, Solidity and Simplicity. These higher-level languages are general purpose – they can be used to solve all sorts of different problems – but the solutions they express are still programs, and they still require programming skills to use them effectively.
In contrast, Marlowe is a domain-specific language (DSL) which is designed to be usable by someone who is expert in a particular field, rather than requiring programming skills to use it. In the case of Marlowe, the domain is the field of financial contracts.
Using a DSL has many advantages beyond its use by non-programmers:
We can ensure that certain sorts of bad programs cannot even be written, by designing those possibilities out of the language. By doing this we can aim to avoid some of the unanticipated exploits which have been a problem for existing blockchains.
We can also more easily check that programs have the properties that we want: for example, in the case of a Marlowe contract, we can make sure that the contract will never fail to make a payment that it should.
Because it is a DSL, we can build special-purpose tools to help people write programs in the language. In the case of Marlowe we can emulate how a contract will behave before it is run for real on the blockchain; this helps us to make sure that the contract we have written is doing what it is intended to.
Marlowe in a nutshell¶
Marlowe is modelled on financial contract DSLs popularised in the last decade or so by academics and enterprises such as LexiFi, which provides contract software in the financial sector. In developing Marlowe, we have adapted these languages to work on blockchain. Marlowe is implemented on the Cardano blockchain, but could equally well be implemented on Ethereum or other blockchain platforms; in this respect it is “platform agnostic” just like modern programming languages like Java and C++. The Marlowe Playground online simulation allows you to experiment with, develop, simulate and analyse Marlowe contracts in your web browser, without having to install any software.
What does a Marlowe contract look like? It is built by combining a small number of building blocks that describe making a payment, making an observation of something in the “real world”, waiting until a certain condition becomes true, and so on.
Timeouts, deposits and commitments¶
Where we differ from non-blockchain approaches is in how we make sure that the contract is followed. This means not only that the instructions of the contract are not disobeyed – “nothing bad happens” – but also that the participants participate and don’t walk away early, leaving money locked up in the contract forever: “good things actually happen”. We do this using timeouts.
A contract can ask a participant to make a deposit of some funds, but obviously the contract cannot actually force a participant to make a deposit. Instead, the contract can wait for a period of time for the participant to commit to the contract: when that period of time expires, the contract moves on to follow some alternative instructions. This prevents a participant stopping a contract by not taking part, thus making sure that “things happen”.
All the constructs of Marlowe that require user participation – including user deposits and user choices – are protected by timeouts. Because of this, it is easy to see that the commitment made by a participant to a contract is finite: we can predict when the contract will have nothing left to do – when it can be closed – at this point any unspent funds left in the contract are refunded to participants, and the contract stops, or terminates. So, any funds put into the contract by a participant can’t be locked up forever: at this point the commitment effectively ends.
What is more, it is easy for us to read off from the contract when it will terminate, we call this the lifetime of the contract: all participants will therefore be able to find out this lifetime before taking part in the contract,
In our model, a running contract cannot force a deposit or a choice to happen: all it can do is to request a deposit or choice from a participant. In other words, for these actions it cannot “push”, but it can “pull”. On the other hand, it can make payments automatically, so some aspects of a Marlowe contract can “push” to make some things happen, e.g. ensuring that a payment is made to a participant by constructing an appropriate transaction output.
Marlowe in action¶
We are working on a production release of Marlowe on the Cardano blockchain early in 2021. From today, you are able to explore Marlowe for yourself, either by downloading it and using the Haskell implementation directly, or by using the online Marlowe Playground simulation tool; these are both covered in subsequent tutorials. These will also cover the details of Marlowe, introduce a series of examples, look deeper into the tools for Marlowe.
We have also worked on developing a set of templates for popular financial instruments taken from the Actus standard, and are able to generate particular contracts from these templates according to the various parameters and options that can be set.
Because Marlowe is a DSL we can work out how Marlowe contracts will behave without running them: this means that we can provide valuable diagnostics to potential participants before they commit to a contract, using static analysis. We can also use logic tools to formally prove properties of Marlowe contracts, giving users the highest level of assurance that their contracts behave as intended.
Where to go to find out more¶
This tutorial covers the latest version of Marlowe, while some of these links cover earlier versions of the language and the playground.
The Marlowe Playground an in-browser development, analysis and simulation environment.
The Marlowe github repository from which you can download Marlowe.
Marlowe: financial contracts on blockchain The paper that introduces an earlier version of the Marlowe language. Nevertheless, it explains the principles and rationale behind its design and implementation.
Marlowe: implementing and analysing financial contracts on blockchain This paper describes the implementation of Marlowe on the Cardano blockchain, and the analysis supported by the Marlowe Playground web-based development and simulation environment.
Efficient static analysis of Marlowe contracts This paper explains how we optimised the static analysis explained in the previous paper.
YouTube playlist: Marlowe: financial contracts on blockchain. A general introduction to Marlowe from April 2020, updated October 2020.
YouTube playlist: The Marlowe Playground An introduction to the playground; some features have changed, and others have been added, since these videos were made in April 2020.