The structure of a Plinth smart contract

This page describes what a Plinth contract project looks like — its shape, not the steps to build it. For a hands-on walk-through, follow Your first smart contract with Plinth instead.

The short version: a Plinth contract is an ordinary Haskell project whose one special move is a Template Haskell splice that turns the on-chain logic into a plain Haskell value. That single idea is what lets a project hold both the on-chain code and the off-chain code that deploys and interacts with it.

An ordinary Haskell project

Because Plinth is a subset of Haskell, a Plinth project is just a cabal package. The entire cabal-install workflow applies unchanged: dependencies are resolved from Hackage and the Cardano package repository (CHaP), code is organised into modules, a library, and executables or test suites, and cabal build builds it.

The single tweak is the compiler. Instead of stock GHC you build with uplc-ghc, most conveniently by setting it once in cabal.project:

with-compiler: /path/to/uplc-ghc
packages: .

This is the persistent equivalent of passing cabal -w /path/to/uplc-ghc on the command line.

On-chain and off-chain in one project

The defining structural feature of a Plinth project is that the same package, built by the same compiler, holds two kinds of code bound for two different places:

  • On-chain code — the validator and minting-policy logic (the scripts that guard spending an output and minting a token), written in the Plinth subset, that ends up as UPLC on the ledger.
  • Off-chain code — ordinary Haskell that prepares, inspects, serialises, and deploys that on-chain code: blueprint generators, tests, and transaction-building.

These are not separate projects that share a data format by convention; they are the same Haskell program. What joins them is a Template Haskell splice.

The bridge: PlutusTx.compile

The on-chain logic starts life as an ordinary Haskell function. You turn it into on-chain code by quoting it and compiling it at compile time:

validatorCode :: CompiledCode (BuiltinData -> BuiltinUnit)
validatorCode = $$(PlutusTx.compile [|| validator ||])

Reading this:

  • [|| validator ||] is a typed Template Haskell quote of the function.
  • $$(PlutusTx.compile ...) runs during compilation. This splice is exactly where the GHC plugin intercepts the quoted code and runs the Plinth-to-UPLC pipeline.
  • the result is a CompiledCode a: an ordinary Haskell value holding the compiled UPLC program. The phantom type a (here BuiltinData -> BuiltinUnit) records the Haskell type the program was compiled from.

The key idea is that the splice freezes the on-chain program into the host program as a value. Once validatorCode is just a value, the rest of the project — the off-chain half — can pick it up and work with it like any other data. That is what lets one project hold both worlds.

(A handful of other Template Haskell helpers — makeLift, makeIsDataIndexed — derive the glue that moves Haskell datatypes across the boundary as on-chain Data. Writing the Plinth code itself, and these helpers, are covered in The Plinth contract language; here we only need the splice.)

Working with CompiledCode off-chain

Everything past the splice is plain Haskell operating on a value — no plugin involved. The plugin was needed only to produce the CompiledCode; what the off-chain code does with it is where most of a project’s non-validator code lives. Typically it:

  • Applies parameters. A parameterised script is a CompiledCode (P -> V); before deployment you bake in its compile-time parameter with unsafeApplyCode (or the checked applyCode) together with liftCode, producing a CompiledCode V. This happens off-chain and changes the resulting script — and therefore its hash. The template does it right at the splice site:

    auctionValidatorScript params =
      $$(PlutusTx.compile [|| auctionUntypedValidator ||])
        `PlutusTx.unsafeApplyCode` PlutusTx.liftCode plcVersion110 params
    
  • Serialises it. serialiseCompiledCode :: CompiledCode a -> SerialisedScript produces the flat-in-CBOR bytes the ledger actually runs (SerialisedScript is a ShortByteString). From those bytes come the script hash and the script address.

    import PlutusLedgerApi.Common (serialiseCompiledCode)
    
    script = serialiseCompiledCode validatorCode
    
  • Describes it as a blueprint. A CIP-57 blueprint can be generated for one or more scripts directly in the off-chain code. Parts of it are derived from the scripts themselves — the argument schemas, the compiled code, its hash — while the rest of the metadata is filled in explicitly. See Generate a blueprint.

  • Builds transactions and tests. The serialised script can be handed to cardano-api (or a test harness) to attach it to a transaction as an inline or reference script, and to exercise the validator off-chain.

A typical layout

Put together, a Plinth project is usually a library of on-chain validators — each exposed as a CompiledCode, often as a function of its parameters — plus executables or test suites for the off-chain side. The project template is laid out exactly this way: the plinth-validators library under src/, and the gen-auction-validator-blueprint and gen-minting-policy-blueprint executables under app/. The library is the on-chain half frozen into values; the executables are the off-chain half consuming them.

Further reading