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.

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.

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

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.

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.

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.

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 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:

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:

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:

• Project packages: defined inside marlowe.haskell.packages

  • e.g. marlowe.haskell.packages.marlowe.components.library

There are other attributes defined in packages.nix.

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: