The main documentation is located here.

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

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

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

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.

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.

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.

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

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.

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.

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.

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.

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!

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:

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