The Plutus Application Framework

Table of Contents

Documentation
Versioning and releases
Working with the project
Nix
- How to set up the IOHK binary caches
- Which attributes to use to build different artifacts
Licensing

The Plutus Application Framework, part of the Plutus Platform, is a framework for developing distributed applications using the Cardano blockchain. For more information about the projects, see the User documentation.

This repository contains:

Plutus Platform
- Libraries which implement the Plutus Application Framework, a framework for writing applications that work with Cardano.
- A selection of end-to-end usecases written with the Plutus Application Framework
- The Plutus Playground, a web-based playground for learning and writing basic Plutus Applications.

Important

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

For people who want to use the Framework, 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 is located here.

The generated Haskell API documentation (haddocks) are here: https://playground.plutus.iohkdev.io/doc/haddock.

Talks

Specifications and design

Plutus Technical Report (draft)

Versioning and releases

PVP reminder:

Two major-version components, A.B
- In this doc: “first-major-version”, “second-major-version”
One minor-version component C
Any number of (meaningless but higher) patch-version components

Versioning

The core plutus-apps 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 the tools are compatible with.
- 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-playground-server, plutus-playground-client, quickcheck-dynamic, etc.) can remain unversioned.

In principle we could just have a single major version, but using two makes it easier to avoid mistakes and clearly expresses the state of the repository.

Branching

There are two protected branches in plutus-apps:

main branch
- Most development should be done in this branch
- Should always target a stable version of cardano-node which is compatible with the current Cardano mainnet.
- The version of transitive dependencies (plutus, cardano-ledger, ouroboros-network, etc.) should be pinned to the ones from cardano-node (or better, cardano-wallet)
- Changes will be backported form main to next-node
next-node branch: should always target the next node release.
- This branch will eventually be merged in main after the Cardano mainnet HF.

Dependency update

The dependency update policy is dependent on the protected branch.

For cardano-node, we define major-version-bound the range of versions which are compatible with a specific era. For example, for the Alonzo era, that would be >= 1.29 && < 1.35. For the Vasil era, that would be >= 1.35 && < 1.36.

Independently of the protected branch:

It should always use the same first-major-version of plutus as the one used by the plutus dependency of cardano-node
It should always be safe to upgrade to a new second-major-version of plutus: at worst this will lead to some code breakage.
It should, unless specified otherwise, use the same version for transitive dependencies (cardano-ledger, ouroboros-network, etc.) with cardano-node
It should pin the major version of cardano-node for all packages
It should pin the first and second-major version of plutus for all packages

main branch:

It should not update cardano-node to a new major-version. In other words, it should use a cardano-node version which is compatible with the current Cardano mainnet
It should use a cardano-wallet version which is compatible with the current cardano-node version

next-node branch:

It may update the cardano-node to a new major-version. In other words, it may use a cardano-node version which is incompatible with the current Cardano mainnet
It may use a cardano-wallet version which is incompatible with the current cardano-node version

Version ranges

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

Packages in plutus-apps which are used downstream should pin the major-version of each other (e.g. plutus-pab-1.0.1 should depend on plutus-contract ^>= 1.0).
Downstream packages should pin at least the first-major-version of plutus-apps packages.
- Upgrading to a new second-major-version should always be safe for working on the current mainnet, 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-apps packages via source-repository-package stanzas should always take tagged commits.

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

Add plutus-apps as a source-repository-package to your cabal.project.
Copy the source-repository-package stanzas from our cabal.project to yours.
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 the Plutus Platform 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. For instance, you would have to build and install this fork of libsodium from source. 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.

How to build the Haskell packages and other artifacts with Nix

Run nix build -f default.nix plutus-apps.haskell.packages.plutus-pab.components.library from the root to build the Plutus PAB 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-pab from the root to build the Plutus PAB library.

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

Deployment

The Plutus Playground is automatically deployed upon certain pushes to GitHub

Staging is deployed from every commit pushed to main (this URL subject to change)
Production is deployed from every release tag (matching vYYYY-MM-DD)

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=

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.

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

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

Example attributes

Project packages: defined inside plutus-apps.haskell.packages
- e.g. plutus-apps.haskell.packages.plutus-pab.components.library

There are other attributes defined in default.nix.

Licensing

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.

mlabs-haskell/plutus-apps