Documentation

Data structure to test a mockchain trace. a is the return typed of the tested trace, prop is the domain in which the properties live. This is not enforced here, but it will often be assumed that prop satisfies IsProp.

Our MockChain naturally instantiate the inner monad with Identity

The state used to run the simulation in Direct

If a UTxO is a TxOutRef with some additional information, this type captures a "stream" of UTxOs.

Errors that can be produced by the blockchain

This is the first layer of our blockchain, which provides the minimal subset of primitives required to perform balancing.

This is the second layer of our blockchain, which provides all the other blockchain primitives not needed for balancing, except transaction validation. This layers is the one where Tweaks are plugged to.

The final layer of our blockchain, adding transaction validation to the mix. This is the only primitive that actually modifies the ledger state.

A newtype wrapper to be used with '-XDerivingVia' to derive instances of MonadBlockChain for any MonadTransControl.

For example, to derive 'MonadBlockChain m => MonadBlockChain (ReaderT r m)', you'd write

deriving via (AsTrans (ReaderT r) m) instance MonadBlockChain m => MonadBlockChain (ReaderT r m)

and avoid the trouble of defining all the class methods yourself.

This represents elements that can be emitted throughout a MockChain run. These elements are either log entries corresponding to internal events worth logging, or aliases for hashables corresponding to elements users wishes to be properly displayed when printed with PrettyCooked

A modal mock chain is a mock chain that allows us to use LTL modifications with Tweaks

IsProp is a common interface for HUnit and QuickCheck tests. It abstracts uses of Assertion and Property for (IsProp prop) => prop, then provide instances for both HU.Asserton and QC.Property.

A MockChainT builds up a stack of monads on top of a given monad m to reflect the requirements of the simulation. It writes a MockChainBook, updates and reads from a MockChainState and throws possible MockChainErrors.

Type of properties over failures

Type of properties over successes

Type of properties over the number of run outcomes. This does not necessitate a PrettyCookedOpts as parameter as an Integer does not contain anything significant that can be pretty printed.

Type of properties over the mockchain journal

Type of properties over the UtxoState

Logging a Skeleton as it is submitted by the user.

Logging a Skeleton as it has been adjusted by the balancing mechanism, alongside fee, and possible collateral utxos and return collateral wallet.

Logging the successful validation of a new transaction, with its id and number of produced outputs.

Logging the fact that utxos provided by the user for balancing have to be discarded for a specific reason.

Logging the fact that utxos provided as collaterals will not be used because the transaction does not involve scripts. There are 2 cases, depending on whether the user has provided an explicit wallet or a set of utxos to be used as collaterals.

Logging the automatic addition of a reference script

Logging the automatic adjusment of a min ada amount

Conjunction of two props

Disjunction of two props

Here we provide our own universsal quantifier instead of forAll, so we can monomorphize it to returning a Property

Returns the current slot number

Wait for a certain slot, or throws an error if the slot is already past

Lifts an equality test to a prop

Apply a Tweak to the (0-indexed) nth transaction in a given trace. Successful when this transaction exists and can be modified.

Apply a Tweak to every transaction in a given trace. This is also successful if there are no transactions at all.

Apply a Tweak to some transaction in the given Trace. The tweak must apply at least once.

This creates the initial MockChainState from an initial distribution by submitting an initial transaction with the appropriate content. The genesis key hash has been taken from https://github.com/input-output-hk/cardano-node/blob/543b267d75d3d448e1940f9ec04b42bd01bbb16b/cardano-api/test/Test/Cardano/Api/Genesis.hs#L60

This is the main entry point of our balancing mechanism. This function takes a skeleton and returns a (possibly) balanced skeleton alongside the associated fee, collateral inputs and return collateral wallet, which might be empty when no script is involved in the transaction. The options from the skeleton control whether it should be balanced, and how to compute its associated elements.

This computes the minimum and maximum possible fee a transaction can cost based on the current protocol parameters and its number of scripts.

This function was originally inspired by https://github.com/input-output-hk/plutus-apps/blob/d4255f05477fd8477ee9673e850ebb9ebb8c9657/plutus-ledger/src/Ledger/Fee.hs#L19

Returns the closed ms interval corresponding to the current slot

Retrieves the ordered list of outputs of the given CardanoTx.

This is useful when writing endpoints and/or traces to fetch utxos of interest right from the start and avoid querying the chain for them afterwards using allUtxos or similar functions.

Same as txOutByRef but throws an error in case of missing utxo. Use this when you know the utxo is present, or when you want an error to be throw when it's not.

Like datumFromTxOutRef, but uses fromBuiltinData to attempt to deserialize this datum into a given type

Resolves an TxOutRef and extracts the value it contains

Extracts a potential OutputDatum from a given TxOutRef

Extracts a potential TxSkelOutDatum from a given TxOutRef

Return the slot that contains the given time. See slotToMSRange for some satisfied equational properties.

Waits until the current slot becomes greater or equal to the slot containing the given POSIX time. Note that that it might not wait for anything if the current slot is large enough.

Wait a given number of ms from the lower bound of the current slot and returns the current slot after waiting.

Wait a given number of ms from the upper bound of the current slot and returns the current slot after waiting.

The infinite range of slots ending before or at the given time

The infinite range of slots starting after or at the given time

Returns the closed ms interval corresponding to the slot with the given number. It holds that

slotToMSRange (getEnclosingSlot t) == (a, b)    ==>   a <= t <= b

and

slotToMSRange n == (a, b)   ==>   getEnclosingSlot a == n && getEnclosingSlot b == n

and

slotToMSRange n == (a, b)   ==>   getEnclosingSlot (a-1) == n-1 && getEnclosingSlot (b+1) == n+1

Returns all validators which guard transaction inputs

look up the UTxOs the transaction consumes, and sum their values.

Go through all of the TxOutRefs in the list and look them up in the state of the blockchain, throwing an error if one of them cannot be resolved.

Validates a skeleton, and retuns the ordered list of produced output references

Validates a skeleton, and erases the outputs

Retrieves the total amount of lovelace deposited in proposals in this skeleton (equal to govActionDeposit times the number of proposals).

Retrieves the required deposit amount for issuing governance actions.

Like define, but binds the result of a monadic computation instead

Same as outputDatumFromTxOutRef but throws an error when the utxo is missing

Same as datumFromTxOutRef but throws an error when the utxo is missing

Like typedDatumFromTxOutRef but throws an error when the utxo is missing

Same as valueFromTxOutRef but throws an error when the utxo is missing

Returns all scripts involved in this TxSkel

This transforms an output into another output which contains the minimal required ada. If the previous quantity of ADA was sufficient, it remains unchanged. This can require a few iterations to converge, as the added ADA will increase the size of the UTXO which in turn might need more ADA.

This goes through all the TxSkelOuts of the given skeleton and updates their ada value when requested by the user and required by the protocol parameters.

Compute the required minimal ADA for a given output

Interprets the staged mockchain then runs the resulting computation with a custom function. This can be used, for example, to supply a custom InitialDistribution by providing runMockChainTFrom.

Same as interpretAndRunWith but using runMockChainT as the default way to run the computation.

Runs a Tweak from a given TxSkel and InitialDistribution within a mockchain

Runs a Tweak from a given TxSkel within a mockchain

Apply a Tweak to the next transaction in the given trace. The order of arguments is reversed compared to somewhere and everywhere, because that enables an idiom like

do ...
   endpoint arguments `withTweak` someModification
   ...

where endpoint builds and validates a single transaction depending on the given arguments. Then withTweak says "I want to modify the transaction returned by this endpoint in the following way".

Given a UTxO search, we can run it to obtain a list of UTxOs.

Search all currently known TxOutRefs together with their corresponding TxOut.

Search all TxOutRefs at a certain address, together with their TxOut. This will attempt to cast the owner of the TxSkelOut to addr so be careful how you use it.

Search all TxOutRefs of a transaction, together with their TxOut.

Search all TxOuts corresponding to given the list of TxOutRefs. Any TxOutRef that doesn't correspond to a known output will be filtered out.

Transform a UtxoSearch by applying a possibly partial monadic transformation on each output in the stream

Same as filterWith but with a pure transformation

Some as filterWithPure, but the transformation is taken from an optic

Same as filterWithPure but the outputs are selected using a boolean predicate, and not modified

A specific version of filterWithPred where outputs must me of type TxSkelOut and the predicate only relies on their value

A specific version of filterWithValuePred when TxSkelOuts are only kept when they contain only ADA

A specific version of filterWithValuePred when TxSkelOuts are only kept when they contain non-ADA assets

Search for UTxOs at a specific address, which only carry address and value information (no datum, staking credential, or reference script).

Same as onlyValueOutputsAtSearch, but also ensures the returned outputs do not contain non-ADA assets. These "vanilla" outputs are perfect candidates to be used for balancing transaction and attaching collaterals.

Some as filterWithPure but with a total transformation

Searches for all outputs containing a given script as reference script

Same as filterWithPure but inverses the predicate

Total value accessible to what's pointed by the address.

List of UTxOs contained in this UtxoPayloadSet

The reference of this UTxO

The value stored in this UTxO

The optional datum stored in this UTxO and whether it is hashed (True) or inline (False)

The optional reference script stored in this UTxO

Combines two MockChainT together

The returned value of the run

All the outputs used throughout the run

The resulting UtxoState of the run

The log entries emitted during the run

The aliases defined during the run

Runs a MockChainT from a default MockChainState

Runs a MockChainT from an initial MockChainState built from a given InitialDistribution.

Executes a MockChainT from the canonical initial state and environment.

See runMockChainTFrom

See runMockChainT

Turns a boolean into a prop

Ensures all elements of a list satisfy a given prop

Ensures at least one element of a list satisfy a given prop

Catches a HUnit test failure, if the test fails.

Asserts whether a set is a subset of another one, both given as lists.

Asserts whether 2 sets are equal, both given as lists.

This takes a Test and transforms it into an actual test case in prop. This is the main function justifying the existence of Test. This runs the traces, ensures there is the right number of outcomes and, depending on the nature of these outcomes, either calls testFailureProp or testSuccessProp. It also uses the aliases emitted during the mockchain run to pretty print messages when applicable.

A convenience helper when using Assertion which allows to replace testCase with testCooked and thus avoid the use of testToProp. Sadly we cannot generalise it with type classes on prop to work for QuichCheck at GHC will never be able to instantiate prop.

Same as testCooked, but for Property

A test template which expects a success from a trace

A test template which expects a failure from a trace

Gives an initial distribution from which the trace will be run

Gives some pretty options to render test messages

Appends a requirements over the emitted log, which will need to be satisfied both in case of success or failure of the run.

Appends a requirements over the resulting UtxoState, which will need to be satisfied both in case of success or failure of the run.

Appends a requirement over the resulting value and state of the mockchain run which will need to be satisfied if the run is successful

Same as withSuccessProp but only considers the returning value of the run

Appends a requirement over the resulting number of outcomes of the run

Appends a requirement over the resulting value and state of the mockchain run which will need to be satisfied if the run is successful

Same as withFailureProp but only considers the returning error of the run

A property to ensure a phase 1 failure

A property to ensure a phase 2 failure

Same as isPhase1Failure with an added predicate on the text error

Same as isPhase2Failure with an added predicate over the text error

Ensures the run has an exact given number of outcomes

Ensures the run has a minimal number of outcomes

Ensures the run has a minimal number of outcomes

Ensures a certain event has been emitted. This uses the constructor's name of the MockChainLogEntry by relying on show being lazy.

Ensures a certain event has not been emitted. This uses the constructor's name of the MockChainLogEntry by relying on show being lazy.

Ensures that the given wallets satisfy certain amount requirements over a list of given asset classes in the end of the run

Ensures that a given wallet possesses exactly a certain amount of a given asset class in the end of the run

A test template which expects a Phase 2 failure

A test template which expects a specific phase 2 error message

A test template which expects a Phase 1 failure

A test template which expects a specific phase 1 error message

A test template which expects a certain number of successful outcomes

A test template which expects a certain number of unsuccessful outcomes