Documentation

Data structure to test a mockchain trace

Slightly more concrete version of UtxoState, used to actually run the simulation.

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

A description of who owns what in a blockchain. Owners are addresses and they each own a UtxoPayloadSet.

The errors that can be produced by the MockChainT monad

Contains methods needed for balancing.

The main abstraction of the blockchain.

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.

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.

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 appearance of a new transaction, after a skeleton has been successfully sent for validation.

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

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

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 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

This function is essentially a copy of 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

Moves n slots fowards

Retrieve 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.

Try to resolve the datum on the output: If there's an inline datum, take that; if there's a datum hash, look the corresponding datum up (with datumFromHash), returning Nothing if it can't be found; if there's no datum or hash at all, return Nothing.

Like resolveDatum, but also tries to use fromBuiltinData to extract a datum of the suitable type.

Try to resolve the validator that owns an output: If the output is owned by a public key, or if the validator's hash is not known (i.e. if validatorFromHash returns Nothing) return Nothing.

Try to resolve the reference script on an output: If the output has no reference script, or if the reference script's hash is not known (i.e. if validatorFromHash returns Nothing), this function will return Nothing.

Return the slot that contains the given time. See slotToTimeInterval 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

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

and

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

and

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

All validators which protect transaction inputs

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

Looks up and resolves the hashed datums on UTxOs the transaction consumes or references, which will be needed by the transaction body.

Looks up the data on UTxOs the transaction consumes and returns their hashes. This corresponds to the keys of what should be removed from the stored datums in our mockchain. There can be duplicates, which is expected.

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.

This transforms an output into another output which necessarily contains at least the minimal required ada. If the previous quantity of ada was sufficient, it remains unchanged. This requires an iterative process, as adding ada into an output can potentially increase its size and thus make it require more minimal ada (although this remains to be witnessed in practice). This approach was inspired by https://github.com/input-output-hk/plutus-apps/blob/8706e6c7c525b4973a7b6d2ed7c9d0ef9cd4ef46/plutus-ledger/src/Ledger/Index.hs#L124

This transforms a skeleton by replacing all its TxSkelOut by their updated variants with their minimal amount of required ada. Any error raised in the transformation process is transformed into an MCEGenerationError

This provides the minimum amount of ada required in a given TxSkelOut. As we need to transform our output into a Cardano output to compute this value, this function can fail.

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.

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".

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

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

Search all currently known TxOutRefs together with their corresponding TxInfo-TxOut.

Search all TxOutRefs at a certain address, together with their TxInfo-TxOut.

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

Search all TxInfo-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 failing monadic "lookup" on every output.

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

A vanilla output only possesses an ada-only value and does not have a staking credential, a datum or a reference script. A vanilla UTxO is a perfect candidate to be used for fee, balancing or collateral.

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

Executes a MockChainT from some initial state; does not convert the MockChainSt into a UtxoState.

Executes a MockChainT from an initial state set up with the given initial value distribution. Similar to runMockChainT, uses the default environment. Returns a UtxoState instead of a MockChainSt. If you need the later, use runMockChainTRaw

Executes a MockChainT from the canonical initial state and environment. The canonical environment uses the default SlotConfig and Cooked.Wallet.wallet 1 as the sole wallet signing transactions.

See runMockChainTRaw

See runMockChainTFrom

See runMockChainT

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.

A test template which expects a success from a trace

A test template which expects a failure from a trace

A test template with no particular requirement on the trace

Appending an initial distribution to a test

Appending printing options to a test

Appending a predicate over the log to a test. This will be used both in case of success or failure of the trace.

Appending a predicate over the return value and state, which will be used in case of success of the trace.

Appending a predicate over the return value, which will be used in case of success of the trace.

Appending a predicate over the return state, which will be used in case of success of the trace.

Appending a predicate over an error which uses the printing options, which will be used in case of failure of the trace.

This takes a test and transforms it into an actual test case in prop.

Ensure that all results produced by the staged mockchain succeed, starting from the default initial distribution

Ensure that all results produced by the staged mockchain fail

A property to ensure a phase 1 failure

A test that succeeds when the trace results in a phase 1 failure

A property to ensure a phase 2 failure

A test that succeeds when the trace results in a phase 2 failure

Same as isPhase1Failure with an added predicate on the text error

Same as testFailsInPhase1 with an added predicate on the text error

Same as isPhase2Failure with an added predicate over the text error

Same as testFailsInPhase2 with an added predicate over the text error