Marlowe Playground
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. 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
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.
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.
How to build the Haskell packages and other artifacts with Nix
Run nix build -f default.nix marlowe.haskell.packages.marlowe.components.library
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.
cabal
How to build the Haskell packages with 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 |
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
.
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:
-
On non-NixOS, edit
/etc/nix/nix.conf
and add the following lines:substituters = https://hydra.iohk.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=
NoteIf you don’t have an
/etc/nix/nix.conf
or don’t want to edit it, you may add thenix.conf
lines to~/.config/nix/nix.conf
instead. You must be a trusted user to do this. -
On NixOS, set the following NixOS options:
nix = { binaryCaches = [ "https://hydra.iohk.io" "https://iohk.cachix.org" ]; binaryCachePublicKeys = [ "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
default.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:
nix build -f default.nix docs.site
-
Project packages: defined inside
marlowe.haskell.packages
-
e.g.
marlowe.haskell.packages.marlowe.components.library
-
There are other attributes defined in default.nix
.