The Plutarch guide is your one-stop shop for getting up to speed on Plutarch!

Note: If you spot any mistakes/have any related questions that this guide lacks the answer to, please don't hesitate to raise an issue. The goal is to have high quality documentation for Plutarch users!

Aside: Not interested in the details? Skip straight to examples!

Overview

Haddock

Haddock documentation of plutus-core, plutus-ledger-api, plutus-tx, and few other upstream library with correctly matched version to latest Plutarch is available:

Go to Haddock

Compiling and Running

• Common Extensions and GHC options
• Evaluation
• Nix binary cache is recommended. Otherwise nix will build from GHC itself.

Use Plutonomicon binary cache via cachix: https://plutonomicon.cachix.org

DO NOT add your user to trusted-users as cachix use suggests because this is insecure.

Introduction and Basic Syntax

The Introduction section serves as a introduction to Plutarch's basic concepts and core syntactic constructs. It will help build a mental model of Plutarch, but is insufficient to write production-ready code.

• Overview
• Untyped Plutus Core (UPLC)
• Plutarch Types
• Plutarch Terms
  • Plutarch Constant Terms
    • Static building of constant Terms with pconstant
    • Dynamic building of constant Terms with pcon
    • Overloaded literals
    • Helper functions
  • Lambdas; Plutarch-level Function Terms.
    • Function Application
• Pattern matching constant Terms with pmatch.
• Strictness and Laziness; Delayed Terms and Forcing
• References

Practical Usage

The Usage section fills in the gaps left by the previous. It illustrates techniques that make Plutarch easier to work with.

• Conditionals
• Recursion
• Using the Plutarch Prelude
• Do syntax with TermCont
• Do syntax with QualifiedDo and Plutarch.Monadic
• Deriving typeclasses for newtypes
• Deriving typeclasses with generics
• plet to avoid work duplication
• Tracing
• Raising errors
• Unsafe functions

Concepts

The Concepts section details additional concepts.

• Hoisting, metaprogramming, and fundamentals
  • Hoisting Operators
• What is the s?
• Data encoding and Scott encoding
  • Data encoding
  • Scott encoding
• Haskell synonym of Plutarch types

Typeclasses

The Typeclasses section discusses the primary typeclasses related to Plutarch.

• PEq & POrd
• PIntegral
• PIsData
• PlutusType, PCon, and PMatch
  • Implementing PlutusType for your own types (Scott Encoding)
  • Implementing PlutusType for your own types (Data Encoding)
  • Implementing PlutusType for your own types (newtype)
• PListLike
• PIsDataRepr & PDataFields
  • All about extracting fields
    • Alternatives to OverloadedRecordDot
  • All about constructing data values
• PTryFrom
  • Laws
  • Implementing PTryFrom
  • PTryFromExcess
  • Recovering only partially

Working with Types

The Types section discusses the core types of Plutarch.

• PInteger
• PBool
• PString
• PByteString
• PUnit
• PBuiltinList
• PList
• PBuiltinPair
• PAsData
• PDataSum & PDataRecord
• PData

Examples

• Basic examples
• Validator & Minting policies

Rules of thumb, Tips, and Tricks

Outside of the fundamental user guide, there are rules of thumb and general guidelines you can follow to improve your Plutarch experience. The Tricks section discusses ways of writing efficient and high quality Plutarch code, as well as rules that can help auditing Plutarch easier.

• Plutarch functions are strict
• Don't duplicate work
  • Where should arguments be pleted?
• Prefer Plutarch level functions
• When to use Haskell level functions?
• The difference between PlutusType/PCon and PLift's pconstant
• Let Haskell level functions take responsibility of evaluation
• The isomorphism between makeIsDataIndexed, Haskell ADTs, and PIsDataRepr
• Prefer statically building constants whenever possible
• Figuring out the representation of a Plutarch type
• Prefer pattern matching on the result of pmatch immediately
• Working with bound fields yielded by pletFields

Common Issues and Troubleshooting

Due to the highly abstracted nature of Plutarch and its utilization of advanced type level concepts, you might face unfamiliar errors. Don't worry, the guide is here to help!

• No instance for PUnsafeLiftDecl a
• Couldn't match representation of type: ... arising from the 'deriving' clause
• Infinite loop / Infinite AST
• Couldn't match type Plutarch.DataRepr.Internal.PUnLabel ... arising from a use of pfield (or getField, or pletFields)
• Expected a type, but "fieldName" has kind GHC.Types.Symbol
• Lifting PAsData
• Type match errors when using pfield/getField (or OverloadedRecordDot to access field)

Useful Links

• Plutonomicon