README.md

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!

Table of Contents

• Overview
  • Compiling and Running
  • Introduction and Basic Syntax
  • Practical Usage
  • Concepts
  • Typeclasses
  • Working with Types
• Examples
• Rules of thumb, Tips, and Tricks
• Common Issues and Troubleshooting
• Useful Links

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

Overview

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
• Interoperability with PlutusTx

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)
• PConstant & PLift
  • Implementing PConstant & PLift
  • Implementing PConstant & PLift for types with type variables (generic types)
• 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
• PTuple
• PAsData
• PDataSum & PDataRecord
• PData

Examples

• Basic examples
• Validator & Minting policies

Also see: examples.

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
• Couldn't match type PLifted (PConstanted Foo) with Foo
• Type match errors when using pfield/getField (or OverloadedRecordDot to access field)

Useful Links

• Plutonomicon