j-mueller / plutus-libs

Tweag Plutus Libraries

• Documentation
• Projects
• Developer Tools and Env
  • IMPORTANT: Setting up the nix cache
  • Updating Plutus

This repository contains our collection of the libraries for developing and auditing Plutus contracts. These libraries are a research prototype under active development, they comes as is with no guarantees whatosever. Check the license for details.

Documentation

The rendered Haddock for the current main branch can be found at https://tweag.github.io/plutus-libs/

Projects

cooked-validators

• Used for writing the first layer of off-chain code: generating and submitting transactions.
• Enables property-based testing of Plutus contracts with no code duplication.
• Interacts seamlessly with Plutus Contract monad.
• Supports loading arbitrary UPLC contracts from bytestrings for testing.

examples

• Example contracts and their test suites written using cooked-validators

lang-pirouette

• Experimental instantiation of pirouette for PlutusIR.

Developer Tools and Environment

A Nix shell development environment is provided. See nix-shell docs. All of the project dependencies, except for Plutus, are handled by nix. Plutus is handled by cabal. This results in a simpler nix setup that is easy to extend with different tools one might need.

IMPORTANT: Configure your nix cache!

Plutus uses a custom GHC version. To avoid having to build this GHC, make sure you set up the IOHK binary nix cache as instructed here.

Seamless Integration with direnv

We recommend using direnv to automatically bring in the nix dependencies when entering the project directory. Just run direnv allow at the root of the repo. To cache the nix environment and make direnv load instantaneously, you can and use nix-direnv. Several editors have support for direnv. If you use emacs, we recomend using envrc-mode.

Nixpkgs and HaskellNix pin

In order to improve reproducibility, nixpkgs and haskell.nix are pinned. See "FAQ/Pinning Nixpkgs" wiki

Pinning is done using niv. Updating them is simple:

nix-shell -p niv --run "niv update nixpkgs"
nix-shell -p niv --run "niv update haskellNix"

Check out the nix/sources.json file, you might need to switch the branch.

Updating Plutus

Are you a contributor and would you like to bump the Plutus version we are depending upon? Because we are not pinning plutus with nix, updating it's a little more manual but it's straightforward.

Our cabal.project file is a copy of the homonym file from plutus-apps, with the addition of plutus-apps themselves in there and a different list of packages to build.

In order to bump plutus, you must:

1. Select the tag you want to update to from plutus-apps.
2. Copy the cabal.project from there
3. Modify the packages: section to build our packages:

   packages:
     cooked-validators
     examples
   

4. Add the relevant setting for linking with libsodium:

   package cardano-crypto-praos
     flags: -external-libsodium-vrf
   

5. Add the plutus-apps dependency in there:

   source-repository-package
     type: git
     location: https://github.com/input-output-hk/plutus-apps.git
     tag: v2021-11-05 -- change the tag to whatever tag you need.
     subdir:
       freer-extras
       playground-common
       plutus-chain-index
       plutus-chain-index-core
       plutus-contract
       plutus-pab
       plutus-ledger
       plutus-use-cases
       quickcheck-dynamic
   

   In this case, we're running with plutus-apps at tag v2021-11-05.
6. Run cabal build all and grab a coffee, this will take a while.

Pre-commit Hooks and CI

Our ci runs ormolu and cabal test for each of our subprojects. In order to help avoid CI failures due to formatting problems, we recommend that you install the pre-commit hook for running ormolu. To do so, simply copy (or link) the script into .git/hooks/pre-commit.