Plutus Core

Table of Contents

• Documentation
  • User documentation
  • Talks
  • Specifications and design
  • Academic papers
• Versioning and releases
  • Versioning
  • Branching and tagging
  • Version ranges
  • Releases
• 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
• Nix
  • How to set up the IOHK binary caches
  • Which attributes to use to build different artifacts
• Licensing

Plutus Core is the scripting language embedded in the Cardano ledger and forms the basis of the Plutus Platform, an application development platform for developing distributed applications using the Cardano blockchain. For more information about the projects, see the User documentation.

This repository contains:

• The implementation, specification, and mechanized metatheory of Plutus Core

• Plutus Tx, the compiler from Haskell to Plutus Core.

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

For people who want to use the project, please consult the User documentation.

Important

This repository used to contain the code for the Plutus Application Framework and Marlowe. These have now moved: Plutus Application Framework Marlowe Please ensure that you make PRs and issues in the appropriate repository!

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 is located here.

Talks

• Functional Smart Contracts on Cardano (2020): an overview of the ideas behind the Plutus Platform.

• The Plutus Platform (2020): an overview of the Platform as a whole (including the Application Framework) at the time.

Specifications and design

• Plutus Technical Report (draft): a technical report and design document for the project.

• Plutus Core Specification: the formal specification of the core language.

• Extended UTXO Model: a design document for the core changes to the Cardano ledger.

Academic papers

• Unraveling Recursion: a description of some of the compilation strategies used in Plutus IR (published version).

• System F in Agda: a formal model of System F in Agda (published version).

• The Extended UTXO Model: a full presentation of the EUTXO ledger extension (published version).

• UTXOma: UTXO with Multi-Asset Support: a full presentation of the multi-asset ledger extension (published version).

• Native Custom Tokens in the Extended UTXO Model: a discussion of the interaction of the multi-asset support with EUTXO (published version).

• Translation Certification for Smart Contracts: a certifier of Plutus IR compiler passes written in Coq.

Versioning and releases

Versioning

The core plutus packages are versioned as follows:

• Package versioning follows the PVP on a best-effort basis (i.e. we will generally try to but we won’t guarantee it).

  • The first-major-version component indicates the "era" which for our purposes means which major version of the Cardano node is being targeted.

  • The second-major-version component is used for releases which are major versions according to the PVP, but which are still compatible with the current "era".

  • The minor-version and below are used as normal.

• Packages which are used downstream should all have the same version.

• Other packages which are not used downstream (e.g. plutus-benchmark) can remain unversioned.

In principle we could just have a single major version, but using two makes it easier to avoid mistakes.

Branching and tagging

The following branching and tagging rules are followed:

• Version X is tagged as vX.

• master is always targeting the next first-major-version.

• First-major-version releases also have a release branch, release/X.

  • Changes will be backported from master to the release branch

  • Subsequent lesser releases will be made from that branch but do not create new branches.

Version ranges

Packages which depend on plutus packages should use version ranges to control which version of those packages they build against.

• Packages in plutus which are used downstream should pin the major-version of each other (e.g. plutus-tx-1.0.1 should depend on plutus-core ^>= 1.0).

• Downstream packages should pin at least the first-major-version of plutus packages.

  • Upgrading to a new second-major-version should always be safe, with at most code breakage (following the PVP). Users may of course want to pin this version as well to avoid such breakage.

• Downstream packages pulling in plutus packages via source-repository-package stanzas should always take tagged commits, or potentially commits from a release branch.

Releases

Currently there is no release process beyond bumping the package versions and making a tag/branch as appropriate.

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

The plutus-starter project provides an example.

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 Plutus Core 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 Agda code, then install Agda and the standard library.

How to build the 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 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 plutus-core from the root to build the Plutus Core library.

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

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. If this file doesn’t exist, go ahead and create it. Remember that nix will use ~/.config/nix/nix.conf over /etc/nix/nix.conf if both files exist.

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=" ];
   };

Note: after changing /etc/nix/nix.conf you must restart the nix-daemon on non-NixOS for the changes to take effect!

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.papers.eutxo

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

There are other attributes defined in default.nix.

Licensing

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