Marlowe on the Cardano Blockchain

Table of Contents

• Documentation
  • User documentation
• Working with the project
  • How to submit an issue
  • How to develop and contribute to the project
  • How to depend on the project from another Haskell project
  • How to build the project’s artifacts
  • Deployment
• Nix
  • How to set up the IOHK binary caches
  • Nix on macOS
  • Which attributes to use to build different artifacts
• Docker compose
  • Accessing the node socket:
• Licensing

Marlowe is a platform for financial products as smart contracts. Marlowe-Cardano is an implementation of Marlowe for the Cardano blockchain, built on top of Plutus.

This repository contains:

• The implementation of the Marlowe domain-specific language.

• Tools for working with Marlowe, including static analysis.

• A selection of examples using Marlowe, including a number based on the ACTUS financial standard.

• The Marlowe Playground, a web-based playground for learning and writing Marlowe Applications.

Important

The rest of this README is focussed on people who want to develop or contribute to Marlowe. For people who want to use Marlowe, please consult the User documentation.

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

User documentation

The main documentation for the whole Plutus ecosystem is located here.

An index of key documentation for Marlowe development is located at https://developers.cardano.org/docs/smart-contracts/marlowe/#resources-for-developing-and-deploying-marlowe-contracts.

Working with the project

How to submit an issue

Issues can be filed in the GitHub Issue tracker.

However, note that this is pre-release software, so we will not usually be providing support.

How to develop and contribute to the project

See CONTRIBUTING, which describes our processes in more detail including development environments; and ARCHITECTURE, which describes the structure of the repository.

How to depend on the project from another Haskell project

None of our libraries are on Hackage, unfortunately (many of our dependencies aren’t either). So for the time being, you need to:

1. Add marlowe as a source-repository-package to your cabal.project.

2. Copy the source-repository-package stanzas from our cabal.project to yours.

3. Copy additional stanzas from our cabal.project as you need, e.g. you may need some of the allow-newer stanzas.

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 nix develop, 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.

• If you want to build our Agda code, then install Agda and the standard library.

How to build the Haskell packages and other artifacts with Nix

Run nix build .#ghc8107-marlowe-runtime-lib-marlowe-runtime from the root to build the Marlowe library.

See Which attributes to use to build different artifacts to find out what other attributes you can build.

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 develop.

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

Run cabal build marlowe from the root to build the Marlowe library.

See the cabal project file to see the other packages that you can build with cabal.

Note	If you get errors about missing shared libraries, try running cabal clean first. If that fails you might have a corrupt cabal store, in which case you should rm -rf ~/.cabal/store and try cabal build all again.

Deployment

Marlowe Run and the Marlowe Playground are 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)

• Marlowe Playground production and Marlowe Run production are deployed from every commit pushed to production

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:

   substituters        = https://cache.iog.io https://iohk.cachix.org https://cache.nixos.org/
   trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= iohk.cachix.org-1:DpRUyj7h7V830dp/i6Nti+NEO2/nhblbov/8MW7Rqoo= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=

   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 = {
     substituters        = [ "https://cache.iog.io" "https://iohk.cachix.org" ];
     trusted-public-keys = [ "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ=" "iohk.cachix.org-1:DpRUyj7h7V830dp/i6Nti+NEO2/nhblbov/8MW7Rqoo=" ];
   };

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

Which attributes to use to build different artifacts

packages.nix defines a package set with attributes for all the artifacts you can build from this repository. These can be built using nix build. For example:

Docker compose

There is a docker compose setup designed to give a local developer mode of the marlowe runtime components, configured in compose.nix.

Currently, this only supports Linux systems.

On Linux, compose.yaml will be automatically set up for the user when entering nix develop.

Running nix run .#re-up will refresh compose.yaml if need be and then restart any services which have changed.

Services currently included:

• marlowe-chain-sync: marlowe-chain-sync for the preprod network.

• marlowe-chain-indexer: marlowe-chain-indexer for the preprod network.

• node: A node for the preprod network.

• postgres: A postgres instance, for marlowe-chain-sync state.

• marlowe—​sync: marlowe-sync for the preprod network.

• marlowe—​indexer: marlowe-indexer for the preprod network.

• marlowe-tx: A marlowe-tx instance.

• marlowe-contract: A marlowe-contract instance.

• marlowe-proxy: A marlowe-proxy instance.

• web: A marlowe-web-server instance.

• otel-collector: A shared opentelemetry collector instance for distributed tracing.

• jaeger: A trace viewer service.

The following commands may be useful:

• docker compose exec postgres /exec/run-sqitch: Run the sqitch migrations for the chain-sync database.

• docker compose exec postgres psql -U postgres -d chain: Run psql in the chain database.

• docker compose port, e.g. docker compose port web 8080 will show the local port that maps to port 8080 for the web service

Accessing the node socket:

The node socket file lives inside a Docker volume. Because it is created by the container, it is owned by root, and needs elevated permissions (via sudo) to use - keep this in mind when using it locally with a tool like cardano-cli.

To list your Docker volumes, use the command docker volume ls. The socket lives in the marlowe-cardano_shared volume. Use docker volume inspect marlowe-cardano_shared to obtain information about the volume. The Mountpoint property shows the directory on the host machine that maps to the volume (one-liner: docker volume inspect marlowe-cardano_shared | jq -r '.[].Mountpoint')

To use this with cardano-cli:

export CARDANO_NODE_SOCKET_PATH=$(docker volume inspect marlowe-cardano_shared | jq -r '.[].Mountpoint')
# -E passes the current environment to sudo
sudo -E cardano-cli ...

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.