mlabs-haskell / plutus-simple-model

Unit testing with resource estimation for Plutus

Plutus simple model

Unit test library for Plutus with estimation of resource usage.

Library defines simple mock model of Blockchain to unit test plutus contracts and estimate usage of resources. What are the benefits for this framework comparing to other test frameworks for Plutus? It's:

• easy to use
• easy to think about
• it has minimal dependency set. It depends only on plutus and cardano-ledger. Ain't no plutus-apps or cardano-node or ouroboros
• works for both Plutus V1 and Plutus V2
• support for Alonzo and Babbage eras
• blazing fast
• can estimate usage of resources with real functions used on Cardano node.
• pure
• good for unit testing of on-chain code
• being fast and pure it's also suitable for property based testing

Quick start guide

See user guide to get started

How to compile the library

Library is compiled with nix, flakes and cabal. Enter developer nix shell with:

nix develop

Inside the nix shell we can run build and tests over make:

make build
make test

It calls cabal under the hood.

How to update docs

Docs are written in mdbook and reside in the docs directory. They are auto-deployed with Git actions on push to main. To run docs locally use mdbook:

cd docs
mdbook serve

plutus-simple-model's Issues

Value in TxIn

https://github.com/mlabs-haskell/plutus-simple-model/blob/f99398b317f2e9d35131178eadcec0fae11a7169/cardano-simple/src/Cardano/Simple/Ledger/Tx.hs#L120C1-L123

Should the TxIn contain the value of the input as well? Or maybe even the whole TxOut?

Upgrade tests to 9.2

#56 added GHC 9.2 support, but the tests were commented out.

This is due to IntersectMBO/cardano-ledger#3092 being needed, but not yet included in https://github.com/input-output-hk/cardano-haskell-packages.

Once this happens, the tests need uncommenting, and ensuring they build and run correctly.

[BUG] Incorrect usage of `withFirstUtxo`

Here the first UTxO is not the one which is desired but rather the one which has reference script in it. We fixed for it in our fork here.

More detailed error messages

It would be great if errors would have more detailed logs.

For example: Transaction outputs should not contain zero Ada.
The log is easy to understand but harder to debug.
Helpful would be in this case for example to have wallet address/script address where this happened.

Functions for cardano-simple

• Move evalScript from TestSingleScript to cardano-simple
• Implement new functions in cs:

  • utxoForTransaction :: 
      Map P.ScriptHash (C.Versioned P.Script) -> 
      Network ->
      Tx era -> 
      Either ToCardanoError (Ledger.UTxO era)
    

  • txBalance :: 
      PParams era -> 
      Map P.ScriptHash (C.Versioned P.Script) ->
      Network ->
      Tx era ->
      Ledger.Value era
    

  • evaluateScriptsInTx ::
      PParams era ->
      Map P.ScriptHash (C.Versioned P.Script) ->
      Network ->
      Tx era ->
      Either (TranslationError (Crypto era)) Alonzo.ExUnits
    

In an appropriate new or existing cs module.

Modify getUtxo, checkBalance and checkUnits in Plutus.Model.Mock to use them.

While you're at it, rename checkUnits to make it clear it is actually executing the scripts and validating the transaction.

Wrongly put extra source files in cabal project description

There is no data folder inside psm & cardano-simple sub directory but still it is mentioned in cabal file like here.

Proper support for Plutarch

Ensure Plutarch is supported in a consistent way with PlutusTx for typed API.

Update to Vasil

We need to update to new cardano-ledger

Invalid minting policy test for plutarch v2

I added test which failed. I didn't find any reason why it behavior like that.
See the branch for more. It is ready to run and see logs.

Remove distinction for reference script UTxOs

Currently, both the API and implementation treat UTxOs with reference scripts as distinct from regular UTxOs. This is both contrary to the spec, and blocks certain use cases.

Allow untyped scripts and data

Currently, we have an implementation of typed scripts that is embedded in the PSM API. This disallows testing with untypesafe data - essentially assuming that PlutusTx library is doing its job correctly. We should enable testing with untyped data.

Ideally the way to do this is to add untyped types and use them exclusively in the core API, adding typing in a layer on top.

Fix config for V2

The Babbage config provided sets the protocol version to V1, which since a recent ledger upgrade won't support V2 scripts.

Fix plan:

• Rename defaultBabbage and defaultBabbageParams to *V1
• Create *V2 versions as per

  plutus-simple-model/psm/test/Spec.hs

  Line 33 in 827b6d6

  ( defaultMockConfig $

• Update test driver

Major version bump (second component, x.X.x.x) and changelog.

make: *** No rule to make target plutus-simple-model.cabal

to reproduce:

git clone
cd plutus-simple-model
nix develop
make build

Factor Cardano layer into separate package

psm has its own lightweight wrapper layer of Cardano functions, kept in the Fork.* hierarchy. These are considered internal modules and not exposed.

The problem is that hedgehog-plutus-simple (and potentially other packages) need many of these functions. The current solution, maintaining a branch of psm where these are exposed, is not satisfactory in the long term.

The proposed solution is to move these modules into a separate package, that both psm and hps can depend on.

• Create a new repository, maybe cardano-simple, based on mlabs-tooling.
• Move the Fork hierarchy to this repo. Probably remove the Fork prefix and add a suffix such as Simple to to each non-novel module
• Switch psm to new dependency
• Switch hps to the new dependency.

When this is done, it may be interesting to see what functionality that hps has duplicated from psm can be removed by exposing more functions from the new Cardano layer, or possibly even moving useful functionality from psm proper to the new layer.

The overarching goal is to move towards a tidier design on all three modules.

All partial/failable functions should use `HasCallStack` in their definition

Purpose: errors have nice callstacks.

A slight Plutus upgrade needed

We've run into a Plutus issue that's been fixed back in July:

IntersectMBO/plutus#4517

Can PSM's dependencies be bumped to include the fix?

Cannot compile cabal after upgrading to Plutus V2

I get the following error when trying to run cabal build:

My cabal.project tries to include Plutus Simple Model as follows:

I'm not sure how I can solve this, it's the latest commit of master branch.

`spend` fails without descriptive error

Plutus.Model.Contract.spend fails with:

Exception: Maybe.fromJust: Nothing
CallStack (from HasCallStack):
  error, called at libraries/base/Data/Maybe.hs:149:21 in base:Data.Maybe
  fromJust, called at src/Plutus/Model/Contract.hs:276:10 in plutus-simple-model-0.5.2.0-4fEbkvuS1hh58koi6xqmzV:Plutus.Model.Contract

It forces user to dive into PSM source code to figure out the reason of the error, which is not the best user experience.

Proposed solution

Make a descriptive error message.
Maybe even take optional error message as a function parameter.

F10 SOM

https://docs.google.com/document/d/10SDJzYHrtmg7Xws5BDbtBIDTLD0cApur4vV0IG1n8Cw/edit#heading=h.fzqqc4lmyeh

`spend'` fails to spend users' funds is some cases

The reason is that strangely enough, lt from Plutus.V1.Ledger.Value can't seem to be correct for all inputs. For example, it doesn't consider a<b if

b (curVal)=Value (
Map [
(5c0ce33a2223eea4d068af7ee5d8972627ce212f44608709c1922107,
Map [
(0x2cb30e42f0336c7644965a977f7e560dc72bac3da94daedf7fd8cc3e24971523,1)
(0x35c6de58fa135aff6c159c5d05330a44206c235f428afa5649720cd805f03d59,1),
(0x567f4ca57846c3226ce5db4504f6d0200d3794efc9809a0fb99dd0e59b6bd808,1),
(0x6673ae665b6ba82c86619ae6ff419d0216db75f2a40bb747271d4af3871c576d,1),
(0x7b6c94cb7a029647f524ac4839599a8fd2c31ef762354d531d0ef6a63336c621,1),
(0x83baee89200833482a9d52bacb603f32e1d1f1dc354c8027cfc0a9932ff6259a,1),
(0xadc9cbfc8448341351192aded5ca67141244034fd60c75281f6225545266d8df,1),
(0xcaae7a64bfc5052e0d52d08add1316731aad69ea665e97aafa1a630a2198b298,1),
(0xe113351fbff67ec6c32d2b7906d49732a06de0144999c6efa4a2e4bda4433948,1)
])
])

and

a (nextVal)=Value (
Map [
(5c0ce33a2223eea4d068af7ee5d8972627ce212f44608709c1922107,
Map [
(0x35c6de58fa135aff6c159c5d05330a44206c235f428afa5649720cd805f03d59,1),
(0x7b6c94cb7a029647f524ac4839599a8fd2c31ef762354d531d0ef6a63336c621,1),
(0xcaae7a64bfc5052e0d52d08add1316731aad69ea665e97aafa1a630a2198b298,1)
])
])  

I am not going to figure out what's wrong with lt right now, though it's worthwhile on its own. Probably it just have different semantics. Instead I am offering a workaround to make things working right now.

[BUG - found cause] zero ada error mistakenly raised

I've posted #15 issue some time ago and when I was digging deeper into the actual problem I've found out that there is probably a bug somewhere and created the minimal reproducible example.

The following code fails the test with the zero ada error even when there should be no such error.

I found out that this happens when I changed this package in the project from commit 64f37881c3c6a1ece104413e95b6a272d22dbfaa to 2077162655a62f9b6404e153eed3ef56c65cad67

EDIT:
The error occurs with both of the commits, so the bug is implemented somewhere further in the past.
Modifying this line:

void $ sendValue admin (Ada.toValue minAdaTxOut <> Value.assetClassValue (fakeCoin (FakeCoin "SMTH")) 10_000_000) user

to this:

void $ sendValue admin (Ada.toValue minAdaTxOut <> Ada.toValue minAdaTxOut  <> Value.assetClassValue (fakeCoin (FakeCoin "SMTH")) 10_000_000) user

solves the error.

However, it should work either way in my opinion.

Buggy code

{-# LANGUAGE NumericUnderscores #-}
{-# LANGUAGE OverloadedStrings #-}

module Spec.MyTest where

import Control.Monad
import Ledger
import qualified Ledger.Value as Value
import Plutus.Test.Model
import qualified Plutus.V1.Ledger.Ada as Ada
import Test.Tasty
import Utils.Helpers (checkBool)

main :: IO ()
main = do
  cfg <- readDefaultBchConfig
  defaultMain $
    testGroup
      "benchmark test suite"
      [ tests cfg
      ]

tests :: BchConfig -> TestTree
tests cfg =
  testGroup
    "Foo"
    [ check True "foo" foo'
    ]
  where
    tokens = Value.assetClassValue (fakeCoin (FakeCoin "SMTH")) 10_000_000

    check :: Bool -> String -> Run Bool -> TestTree
    check = checkBool cfg (Ada.adaValueOf 100_000_000 <> tokens)

    foo' = do
      user <- newUser mempty
      admin <- getMainUser
      void $ sendValue admin (Ada.toValue minAdaTxOut <> Value.assetClassValue (fakeCoin (FakeCoin "SMTH")) 10_000_000) user
      foo user

foo :: PubKeyHash -> Run Bool
foo user = do
  admin <- getMainUser
  let spendVal = Ada.toValue minAdaTxOut
  sp <- sendValue admin spendVal user >> spend user spendVal
  void $ Plutus.Test.Model.signTx user (userSpend sp <> payToPubKey admin spendVal) >>= sendTx
  noErrors

`spendScript[Ref]` datum parameter purpose?

What's the purpose of the Datum parameter since the actually used datum that is sent to validator is the actual one that is attached to the UTXO?

plutus-simple-model/psm/src/Plutus/Model/Contract.hs

Line 467 in 450e278

spendScript ::

I.e. when I have a UTXO at the script address with datum "BUM" and use the on this UTXO:

spendScript script oref () "Hello"

Then when I send the transaction, the datum that arrives to the validator is the "BUM" datum instead of the "Hello" datum.

Maybe the Datum parameter could be removed to prevent confusion?

[BUG] Transaction ID is wrongly exposed

Transaction id which applyTx uses internally is not the same which is shown in logs by use of txStatId. Here is the fix which we did in our fork for it: geniusyield@e506897.

Github Pages 404

Hi everyone!

The docs at https://mlabs-haskell.github.io/plutus-simple-model/ are down.

Confusing constructor of Ada type

Ada's constructor is Lovelace.
It is expected one find inside of the constructor Lovelace lovelaces, but there are adas as the usage in all tests shows. However it wrapped to Lovelace without any conversion. Why?
To get Lovelace there is a function adaToLovelace which is not type safe.

If I didn't miss anything why it made that way, let rename Lovelace constructor to Ada at least. (1)
Or keep Constructor as it is, but not export getLovelace and expose extra function mkAda and fromAda to construct Ada type and get its values. Well mkAda == asAda which is not used. (2)

In case of (2) the function

adaValue :: Integer -> Value
adaValue = ada . Lovelace

could be refactored

adaValue :: Integer -> Value
adaValue = ada . asAda

`spend` failing with `fromJust` error

The spend function should fail with more useful error message.
The change could be as proposed here #67 (comment)

Utilities for Plutarch scripts

Implement functions in Plutus.Model.Validator.Vx for Plutarch.

• From the appropriate Plutarch type to TypedValidator
• For validators, minting policies and staking validators
• For V1 and V2

Remember to add a CHANGELOG entry and bump the minor version number (C in A.B.C.D).