Skip to main content

Marlowe

Get started with Marlowe​

Marlowe is a domain-specific language (DSL) that enables users to create blockchain applications that are specifically designed for financial contracts.

If you want to learn Marlowe from the ground up, start with Marlowe Tutorial, or jump right into the Marlowe Playground:

Marlowe Playground

On the Cardano Forum, you can discuss Marlowe or if you prefer Telegram, there is a special Marlowe Telegram Group.

The Marlowe platform​

When compared to a Turing-complete language, the Marlowe DSL provides significantly greater security, certainty, guarantees of termination, and behavior correctness.

The design guarantees the following:

  • Contracts are finite. No recursion or loops.
  • Contracts will terminate. Timeout on all actions.
  • Contracts have a defined lifetime.
  • No assets retained on close.
  • Conservation of value.

Marlowe Playground​

The Marlowe Playground is a plug-and-play smart contract builder and simulator that is simple to use, visual, and modular. Build, simulate, and analyze Marlowe contracts in this 4-minute tour of the Marlowe Playground.

Resources for Developing and Deploying Marlowe Contracts​

How do I run my Marlowe contract on the Cardano blockchain?​

  1. Design your contract using Marlowe Playground.
  2. Press the Send to Simulator button and then press Download as JSON to download your contract in JSON format.
  3. If you want to run your contract at the command line using marlowe-cli, install marlowe-cli and follow the instructions Running Contracts with Marlowe CLI. A video lecture playlist Marlowe CLI provides an overview of the marlowe-cli tool.
  4. If you want to run your contract in a Jupyter notebook, then use git to clone github.com/input-output-hk/marlowe-cardano, run nix develop --command jupyter-lab from the marlowe-cli/ folder, open the notebook Marlowe CLI Lecture 4, and follow the instructions. A video lecture Running a Marlowe Contract with Marlowe CLI demonstrates running a contract from within a Jupyter notebook.
  5. If you want to run your contract from the command-line using the Marlowe Runtime backend, then follow the tutorial for Marlowe Runtime. A video Marlowe Runtime Tutorial demonstrates its use.
  6. If you want to run your contract using Marlowe Lambda, follow the example for using Marlowe Lambda from the command line or study the example web application for Marlowe Lambda. The video Marlowe Lambda in the Browser demonstrate the use of Marlowe Lambda.

High level technical summary​

Marlowe is implemented for the Cardano blockchain as a validator script that uses the Marlowe DSL in transaction datums for describing the contract states.

The script is implemented in Plutus here and plays a crucial role in validating state transitions for Marlowe contracts. Its purpose is to ensure that transitions caused by transactions comply with both the general rules defined in the Marlowe specification and the current state of the contract, as described in the datum using the Marlowe DSL.

One important rule enforced by the Marlowe validator is that a transaction can only consume a single UTXO and output at most one from the same Marlowe script address. Consequently, a Marlowe contract can be envisioned as a chain of transactions that concludes with a transaction consuming an input from the Marlowe address but producing no output to the same address.

When a transaction consumes the final UTXO of a contract chain without outputting a new UTXO to the same validator address, it indicates the closure of the contract. Such a transaction will contain a redeemer but does not require a datum.

A transaction that consumes the final UTXO and outputs a new one to the same validator address, effectively extending the contract's transaction chain, will also include a redeemer describing the action being applied to the previous state. Additionally, a datum is required to describe the new contract state using the Marlowe DSL. The validator script applies the action to the previous state and returns true (allowing the transaction) only if the transition is permitted by the previous state and results in the provided new state.

Marlowe contracts using the same validator version will utilize the same script address by default. However, it is also possible to derive a staked version of the script address. In this case, only the payment part of the address remains constant for a specific script version. To identify a transaction containing a Marlowe contract, one needs to examine the payment part of the address, which would correlate to a well-known script hash for a validator script version.

Validator versions​

Currently, there is only a single known implementation of Marlowe available for Cardano: input-output-hk/marlowe-cardano.

The well-known versions of the validator script are specified in the ScriptRegistry.hs file.

Version hashes as of January 20, 2024:

Marlowe uses two validators: the semantics validator for the Marlowe DSL and a role-payout validator that allows the holder of a role token to withdraw funds paid by the semantics validator. There is also an optional open-role validator which enables just-in-time assignment of roles to a contract.

VersionTechnical NotesHash for Semantics ValidatorHash for Role-Payout ValidatorHash for Open-Role Validator
V5Optimized using PlutusTx.asData377325ad84a55ba0282d844dff2d5f0f18c33fd4a28a0a9d73c6f60dfcb8885eb5e4f9a5cfca3c75e8c7280e482af32dcdf2d13e47d05d272722e12a53dfb4fe3742b8a2c0534bd16b0b5ae492a3d76554bbe8a5
v4Optimized using PlutusTx 1.156027a8010c555a4dd6b08882b899f4b3167c6e4524047132202dd984fdade3b86107bc715037b468574dd8d3f884a0da8c9956086b9a1a5136a5c7e49a6b11c7fb65fb61db69ed5ceaa35326af9d952fd30185c0
v3Recompiled with Node 8.1.2 dependenciesd85fa9bc2bdfd97d5ebdbc5e3fc66f7476213c40c21b73b41257f09d10ec7e02d25f5836b3e1098e0d4d8389e71d7a97a57aa737adc1d1fab1d61d0c8a3c0f081a7ccebf0050e3f2c9751e82a4f3953a769dddfb
v2Changes in response to audit2ed2631dbb277c84334453c5c437b86325d371f0835a28b910a91a6ee165610232235bbbbeff5b998b233daae42979dec92a6722d9cda989
v1Audited6a9391d6aa51af28dd876ebb5565b69d1e83e5ac7861506bd29b56b049076eab20243dc9462511fb98a9cfb719f86e9692288139b7c91df3

More resources​

Documentation & overview​

GitHub repositories​

Developer Discussions​

Specifications​

Testing and debugging​

Tools​

  • Marlowe CLI: a command-line interface for running Marlowe contracts on the Cardano blockchain.
  • Marlowe Runtime: an application back-end for running Marlowe contracts on the Cardano blockchain.
  • Marlowe Lambda: an AWS Lambda client for Marlowe Runtime.

Examples​

Videos​

Presentations​

Further Tutorials​

Metrics, Adoption, Audit​