Plutus Platform

Table of Contents

• How to use the project
  • Prerequisites
  • How to get started using the platform
  • How to build the Haskell packages and other artifacts
  • How to get the most recent documentation PDFs from CI
• Where to go next
  • Where to find tutorials
  • How to submit an issue
  • How to communicate with us
  • How to develop and contribute to the project
• Nix
  • How to set up the IOHK binary caches
  • Nix on macOS
  • Which attributes to use to build different artifacts

The Plutus Platform enables you to:

• Work with Plutus Core, the smart contract language embedded in the Cardano ledger.

• Write Haskell programs that create and use embedded Plutus Core programs using Plutus Tx.

• Write smart contract executables which can be distributed for use with the Plutus Smart Contract Backend.

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

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.

How to use the project

This section contains brief information about how to use this project. For development work see How to develop and contribute to the project for more information.

Prerequisites

The Haskell libraries in the Plutus Platform can be built in a number of ways. The prerequisites depend on how you want to build the libraries. The other artifacts (docs etc.) are most easily built with Nix, so we recommend installing it regardless.

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

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.

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

How to get started using the platform

The plutus-starter repository contains a starter setup.

How to build the Haskell packages and other artifacts

How to build Haskell packages and other artifacts with Nix

Run nix build -f default.nix plutus.haskell.packages.plutus-core.components.library from the root to build the Plutus Core library.

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

How to build Haskell packages with cabal

Run cabal build plutus-core from the root to build the Plutus Core library.

Note	you must have R installed for this to work. R Installation

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

How to build the Haskell packages with stack

Run stack build plutus-core from the root to build the Plutus Core library. The stack build is less well supported than the cabal build, we do not promise that it will work.

See the stack project file to see the other projects that you can build with stack.

How to get the most recent documentation PDFs from CI

Specifications and design

• Plutus Technical Report (draft)

• Plutus Core Specification

• Extended UTXO Model

Academic papers

• Unraveling Recursion (published version)

• System F in Agda (published version)

• The Extended UTXO Model (in press)

• UTXOma: UTXO with Multi-Asset Support (in press)

• Native Custom Tokens in the Extended UTXO Model (in press)

Where to go next

Where to find tutorials

The doc folder contains the documentation site.

To build a full HTML version of the site that you can view locally, build the docs.site attribute using Nix.

The online version of the tutorial can be found here

How to submit an issue

User 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 communicate with us

We’re active on the Cardano forum. Tag your post with the plutus tag so we’ll see it.

Use the Github issue tracker for bugs and feature requests, but keep other discussions to the forum.

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.

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

   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 = {
     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

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 plutus.haskell.packages.plutus-core

Example attributes

• Project packages: defined inside plutus.haskell.packages

  • e.g. plutus.haskell.packages.plutus-core.components.library

• Documents: defined inside docs

  • e.g. docs.plutus-core-spec

• Development scripts: defined inside dev

  • e.g. dev.scripts.fixStylishHaskell

There are other attributes defined in default.nix.