Marlowe Playground

Table of Contents

• Documentation
• Working with the project
  • How to submit an issue
  • How to develop and contribute to the project
  • How to build the project’s artifacts
  • Deployment
• Nix
  • How to set up the IOHK binary caches
  • Nix on macOS
• Licensing

Marlowe is a platform for financial products as smart contracts. Marlowe Playground is a development tool that helps build and simulate Marlowe Contracts.

Related projects:

• Marlowe: Marlowe language specification

• Marlowe Cardano: Implementation of the Marlowe Language for the Cardano Blockchain. Also haskell lib.

• PureScript Marlowe: PureScript implementation of the Marlowe language for the Cardano Blockchain.

Important

The rest of this README is focussed on people who want to develop or contribute to Marlowe.

Important

DO NOT IGNORE THIS If you want to use Nix with this project, make sure to set up the IOHK binary cache. If you do not do this, you will end up building GHC, which takes several hours. If you find yourself building GHC, STOP and fix the cache.

Documentation

Working with the project

How to submit an issue

Issues can be filed in the GitHub Issue tracker.

How to develop and contribute to the project

See CONTRIBUTING, which describes our processes in more detail including development environments.

How to build the project’s artifacts

This section contains information about how to build the project’s artifacts for independent usage. For development work see How to develop and contribute to the project for more information.

Prerequisites

The Haskell libraries in the Marlowe project are built with cabal and Nix. The other artifacts (docs etc.) are also most easily built with Nix.

Nix

Install Nix (recommended). following the instructions on the Nix website.

Make sure you have read and understood the cache warning. DO NOT IGNORE THIS.

See Nix for further advice on using Nix.

Non-Nix

You can build some of the Haskell packages without Nix, but this is not recommended and we don’t guarantee that these prerequisites are sufficient. If you use Nix, these tools are provided for you via shell.nix, and you do not need to install them yourself.

• If you want to build our Haskell packages with cabal, then install it.

• If you want to build our Haskell packages with stack, then install it.

Using Std

This project is managed by std. It provides a CLI and TUI for navigating all buildable artifacts in the project. To use it, you must enter the project dev shell. You can do this by running the command nix develop from the repo root, or if you are a direnv user, run direnv allow in the repo root and direnv will automatically load the dev shell for you when you cd into the repo and refresh it when it changes.

Upon entering the dev shell, you will be shown a MOD (message of the day) that lists the available commands. You can also launch the std TUI with the std command. It will display a navigable menu of all build actions defined for this project. You can invoke any of the commands from the TUI, or directly using the std CLI. For instance, to build the marlowe-playground-server, run the command std //marlowe-playground/packages/marlowe-playground-server:build.

You can get tab-completion for the std CLI by running the command source <(std _carapace).

How to build the Haskell packages with cabal

The Haskell packages can be built directly with cabal. We do this during development (see How to develop and contribute to the project). The best way is to do this is inside a nix-shell.

Note	For fresh development setups, you also need to run cabal update.

Run cabal build all from the root to build all artifacts.

Deployment

The Marlowe Playground is automatically deployed upon certain pushes to GitHub

• Marlowe Playground staging and Marlowe Run staging are deployed from every commit pushed to main (these URLs subject to change)

For more details, including instructions for setting up ad hoc testing deployments, see the plutus-ops repo.

Nix

How to set up the IOHK binary caches

Adding the IOHK binary cache to your Nix configuration will speed up builds a lot, since many things will have been built already by our CI.

If you find you are building packages that are not defined in this repository, or if the build seems to take a very long time then you may not have this set up properly.

To set up the cache:

1. On non-NixOS, edit /etc/nix/nix.conf and add the following lines:

   experimental-features = nix-command flakes
   substituters        = "https://cache.nixos.org" "https://cache.iog.io "https://marlowe-playground.cachix.org"
   trusted-public-keys = "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= marlowe-playground.cachix.org-1:8TmdbVgcB4QzTmuzLxNdaCxdc8ZVI9S8eeeXsY9stxo="

   Note	If you don’t have an /etc/nix/nix.conf or don’t want to edit it, you may add the nix.conf lines to ~/.config/nix/nix.conf instead. You must be a trusted user to do this.

2. On NixOS, set the following NixOS options:

   nix.settings = {
     experimental-features = [ "nix-command" "flakes" ];
     substituters = [
       "https://cache.nixos.org"
       "https://cache.iog.io"
     ];
     trusted-public-keys = [
       "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ="
     ];
   };

Nix on macOS

Nix on macOS can be a bit tricky. In particular, sandboxing is disabled by default, which can lead to strange failures.

These days it should be safe to turn on sandboxing on macOS with a few exceptions. Consider setting the following Nix settings, in the same way as in previous section:

sandbox = true
extra-sandbox-paths = /System/Library/Frameworks /System/Library/PrivateFrameworks /usr/lib /private/tmp /private/var/tmp /usr/bin/env

Changes to /etc/nix/nix.conf may require a restart of the nix daemon in order to take affect. Restart the nix daemon by running the following commands:

sudo launchctl stop org.nixos.nix-daemon
sudo launchctl start org.nixos.nix-daemon

Licensing

You are free to copy, modify, and distribute Marlowe under the terms of the Apache 2.0 license. See the LICENSE and NOTICE files for details.