Safe Haskell	None
Language	Haskell2010

Test.QuickCheck.ContractModel.ThreatModel

Contents

Transaction modifiers
- Types
- Modifiers
Threat models
Cardano API helpers
- Addresses
- Datums
Pretty printing

Description

The threat modelling framework allows you to write down and test properties of modifications of valid transactions.

A threat model is represented by a value in the ThreatModel monad, and is evaluated in the context of a single valid transaction and the chain state at the point it validated (a ThreatModelEnv). Transactions and chain states can most easily be obtained using a ContractModelResult from runContractModel, but they can in principle come from anywhere.

As an example, here is a ThreatModel that checks that any interaction with myScript requires theToken to be present:

    tokenThreatModel :: ThreatModel ()
    tokenThreatModel = do
      ensureHasInputAt myScript

      let hasToken out = theToken `leqValue` valueOf out
      i <- anyInputSuchThat  hasToken
      o <- anyOutputSuchThat hasToken

      shouldNotValidate $ changeValueOf i (valueOf i <> negateValue theToken)
                       <> changeValueOf o (valueOf o <> negateValue theToken)

For a more complex example see Test.QuickCheck.ContractModel.ThreatModel.DoubleSatisfaction.

Synopsis

data TxModifier
data Input = Input {
- inputTxOut :: TxOut CtxUTxO Era
- inputTxIn :: TxIn
}
data Output = Output {
- outputTxOut :: TxOut CtxTx Era
- outputIx :: TxIx
}
type Datum = TxOutDatum CtxTx Era
type Redeemer = ScriptData
class IsInputOrOutput t where
- changeAddressOf :: t -> AddressAny -> TxModifier
- changeValueOf :: t -> Value -> TxModifier
- changeDatumOf :: t -> Datum -> TxModifier
- addressOf :: t -> AddressAny
- valueOf :: t -> Value
addOutput :: AddressAny -> Value -> Datum -> TxModifier
removeOutput :: Output -> TxModifier
addKeyInput :: AddressAny -> Value -> Datum -> TxModifier
addPlutusScriptInput :: PlutusScript PlutusScriptV2 -> Value -> Datum -> Redeemer -> TxModifier
addSimpleScriptInput :: SimpleScript SimpleScriptV2 -> Value -> TxModifier
removeInput :: Input -> TxModifier
changeRedeemerOf :: Input -> Redeemer -> TxModifier
changeValidityRange :: (TxValidityLowerBound Era, TxValidityUpperBound Era) -> TxModifier
changeValidityLowerBound :: TxValidityLowerBound Era -> TxModifier
changeValidityUpperBound :: TxValidityUpperBound Era -> TxModifier
replaceTx :: Tx Era -> UTxO Era -> TxModifier
data ThreatModel a
data ThreatModelEnv = ThreatModelEnv {
- currentTx :: Tx Era
- currentUTxOs :: UTxO Era
- pparams :: ProtocolParameters
}
runThreatModel :: ThreatModel a -> [ThreatModelEnv] -> Property
assertThreatModel :: ThreatModel a -> ProtocolParameters -> ContractModelResult state -> Property
threatPrecondition :: ThreatModel a -> ThreatModel a
inPrecondition :: ThreatModel Bool
ensure :: Bool -> ThreatModel ()
ensureHasInputAt :: AddressAny -> ThreatModel ()
shouldValidate :: TxModifier -> ThreatModel ()
shouldNotValidate :: TxModifier -> ThreatModel ()
data ValidityReport = ValidityReport {
- valid :: Bool
- errors :: [String]
}
validate :: TxModifier -> ThreatModel ValidityReport
getThreatModelEnv :: ThreatModel ThreatModelEnv
originalTx :: ThreatModel (Tx Era)
getTxInputs :: ThreatModel [Input]
getTxOutputs :: ThreatModel [Output]
getRedeemer :: Input -> ThreatModel (Maybe Redeemer)
forAllTM :: Show a => Gen a -> (a -> [a]) -> ThreatModel a
pickAny :: Show a => [a] -> ThreatModel a
anySigner :: ThreatModel (Hash PaymentKey)
anyInputSuchThat :: (Input -> Bool) -> ThreatModel Input
anyOutputSuchThat :: (Output -> Bool) -> ThreatModel Output
counterexampleTM :: String -> ThreatModel ()
tabulateTM :: String -> [String] -> ThreatModel ()
collectTM :: Show a => a -> ThreatModel ()
classifyTM :: Bool -> String -> ThreatModel ()
monitorThreatModel :: (Property -> Property) -> ThreatModel ()
monitorLocalThreatModel :: (Property -> Property) -> ThreatModel ()
projectAda :: Value -> Value
leqValue :: Value -> Value -> Bool
keyAddressAny :: Hash PaymentKey -> AddressAny
scriptAddressAny :: ScriptHash -> AddressAny
isKeyAddressAny :: AddressAny -> Bool
txOutDatum :: ScriptData -> TxOutDatum CtxTx Era
toScriptData :: ToData a => a -> ScriptData
datumOfTxOut :: TxOut ctx Era -> TxOutDatum ctx Era
paragraph :: [String] -> String
prettyAddress :: AddressAny -> Doc
prettyValue :: Value -> Doc
prettyDatum :: Datum -> Doc
prettyInput :: Input -> Doc
prettyOutput :: Output -> Doc

Transaction modifiers

Types

data TxModifier Source #

The type of transaction modifiers. When combined using the monoid instance, individual modifications are applied in left-to-right order.

Instances

Instances details

Semigroup TxModifier Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel.TxModifier Methods (<>) :: TxModifier -> TxModifier -> TxModifier Source # sconcat :: NonEmpty TxModifier -> TxModifier Source # stimes :: Integral b => b -> TxModifier -> TxModifier Source #
Monoid TxModifier Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel.TxModifier Methods mempty :: TxModifier Source # mappend :: TxModifier -> TxModifier -> TxModifier Source # mconcat :: [TxModifier] -> TxModifier Source #

data Input Source #

A transaction input reference togheter with the corresponding TxOut from the UTxO set.

Constructors

Input
Fields inputTxOut :: TxOut CtxUTxO Era inputTxIn :: TxIn

Instances

Instances details

Show Input Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel.TxModifier Methods showsPrec :: Int -> Input -> ShowS Source # show :: Input -> String Source # showList :: [Input] -> ShowS Source #
IsInputOrOutput Input Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel.TxModifier Methods changeAddressOf :: Input -> AddressAny -> TxModifier Source # changeValueOf :: Input -> Value -> TxModifier Source # changeDatumOf :: Input -> Datum -> TxModifier Source # addressOf :: Input -> AddressAny Source # valueOf :: Input -> Value Source #

data Output Source #

A transaction output paired with its index in the transaction.

Constructors

Output
Fields outputTxOut :: TxOut CtxTx Era outputIx :: TxIx

Instances

Instances details

Show Output Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel.TxModifier Methods showsPrec :: Int -> Output -> ShowS Source # show :: Output -> String Source # showList :: [Output] -> ShowS Source #
IsInputOrOutput Output Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel.TxModifier Methods changeAddressOf :: Output -> AddressAny -> TxModifier Source # changeValueOf :: Output -> Value -> TxModifier Source # changeDatumOf :: Output -> Datum -> TxModifier Source # addressOf :: Output -> AddressAny Source # valueOf :: Output -> Value Source #

type Datum = TxOutDatum CtxTx Era Source #

Type synonym for datums. The CtxTx context means that the actual datum value can be present, not just the hash.

type Redeemer = ScriptData Source #

Redeemers are plain ScriptData.

Modifiers

class IsInputOrOutput t where Source #

Functions common to both Inputs and Outputs.

Methods

changeAddressOf :: t -> AddressAny -> TxModifier Source #

Change the target address of an input or an output. For outputs this means redirecting an output to a different address, and for inputs it means modifying the UTxO set, changing the owner of the given input.

Note: Does not work for script inputs.

changeValueOf :: t -> Value -> TxModifier Source #

Change the value of an input or an output.

changeDatumOf :: t -> Datum -> TxModifier Source #

Change the datum on an input or an output.

addressOf :: t -> AddressAny Source #

Get the address (pubkey or script address) of an input or an output.

valueOf :: t -> Value Source #

Get the value at an input or an output.

Instances

Instances details

IsInputOrOutput Input Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel.TxModifier Methods changeAddressOf :: Input -> AddressAny -> TxModifier Source # changeValueOf :: Input -> Value -> TxModifier Source # changeDatumOf :: Input -> Datum -> TxModifier Source # addressOf :: Input -> AddressAny Source # valueOf :: Input -> Value Source #
IsInputOrOutput Output Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel.TxModifier Methods changeAddressOf :: Output -> AddressAny -> TxModifier Source # changeValueOf :: Output -> Value -> TxModifier Source # changeDatumOf :: Output -> Datum -> TxModifier Source # addressOf :: Output -> AddressAny Source # valueOf :: Output -> Value Source #

addOutput :: AddressAny -> Value -> Datum -> TxModifier Source #

Add a new output of any type (public key or script)

removeOutput :: Output -> TxModifier Source #

Remove an output of any type.

addKeyInput :: AddressAny -> Value -> Datum -> TxModifier Source #

Add a new public key input.

addPlutusScriptInput :: PlutusScript PlutusScriptV2 -> Value -> Datum -> Redeemer -> TxModifier Source #

Add a plutus script input.

addSimpleScriptInput :: SimpleScript SimpleScriptV2 -> Value -> TxModifier Source #

Add a simple script input.

removeInput :: Input -> TxModifier Source #

Remove an input of any type.

changeRedeemerOf :: Input -> Redeemer -> TxModifier Source #

Change the redeemer of a script input.

changeValidityRange :: (TxValidityLowerBound Era, TxValidityUpperBound Era) -> TxModifier Source #

Change the validity range of the transaction.

changeValidityLowerBound :: TxValidityLowerBound Era -> TxModifier Source #

Change the validity lower bound of the transaction.

changeValidityUpperBound :: TxValidityUpperBound Era -> TxModifier Source #

Change the validity upper bound of the transaction.

replaceTx :: Tx Era -> UTxO Era -> TxModifier Source #

The most general transaction modifier. Simply replace the original transaction and UTxO set by the given values. In most cases the modifiers above should be sufficient.

Threat models

data ThreatModel a Source #

The threat model monad is how you construct threat models. It works in the context of a given transaction and the UTxO set at the point where the transaction was validated (see ThreatModelEnv) and lets you construct properties about the validatity of modifications of the original transaction.

Instances

Instances details

Monad ThreatModel Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel Methods (>>=) :: ThreatModel a -> (a -> ThreatModel b) -> ThreatModel b Source # (>>) :: ThreatModel a -> ThreatModel b -> ThreatModel b Source # return :: a -> ThreatModel a Source #
Functor ThreatModel Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel Methods fmap :: (a -> b) -> ThreatModel a -> ThreatModel b Source # (<$) :: a -> ThreatModel b -> ThreatModel a Source #
MonadFail ThreatModel Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel Methods fail :: String -> ThreatModel a Source #
Applicative ThreatModel Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel Methods pure :: a -> ThreatModel a Source # (<>) :: ThreatModel (a -> b) -> ThreatModel a -> ThreatModel b Source # liftA2 :: (a -> b -> c) -> ThreatModel a -> ThreatModel b -> ThreatModel c Source # (>) :: ThreatModel a -> ThreatModel b -> ThreatModel b Source # (<*) :: ThreatModel a -> ThreatModel b -> ThreatModel a Source #

data ThreatModelEnv Source #

The context in which a ThreatModel is executed. Contains a transaction, its UTxO set and the protocol parameters. See getThreatModelEnv and originalTx to access this information in a threat model.

Constructors

ThreatModelEnv
Fields currentTx :: Tx Era currentUTxOs :: UTxO Era pparams :: ProtocolParameters

Instances

Instances details

Show ThreatModelEnv Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel Methods showsPrec :: Int -> ThreatModelEnv -> ShowS Source # show :: ThreatModelEnv -> String Source # showList :: [ThreatModelEnv] -> ShowS Source #

runThreatModel :: ThreatModel a -> [ThreatModelEnv] -> Property Source #

Evaluate a ThreatModel on a list of transactions with their context. Fails the property if the threat model fails on any of the transactions.

assertThreatModel :: ThreatModel a -> ProtocolParameters -> ContractModelResult state -> Property Source #

Evaluate a ThreatModel on the result of running a ContractModel test (see runContractModel). Checks the threat model on all transactions produced by the test.

Preconditions

threatPrecondition :: ThreatModel a -> ThreatModel a Source #

Check a precondition. If the argument threat model fails, the evaluation of the current transaction is skipped. If all transactions in an evaluation of runThreatModel are skipped it is considered a discarded test for QuickCheck.

Having the argument to threatPrecondition be a threat model computation instead of a plain boolean allows you do express preconditions talking about the validation of modified transactions (using shouldValidate and shouldNotValidate). See ensure for the boolean version.

inPrecondition :: ThreatModel Bool Source #

Returns True if evaluated under a threatPrecondition and False otherwise.

ensure :: Bool -> ThreatModel () Source #

Same as threatPrecondition but takes a boolean and skips the test if the argument is False.

ensureHasInputAt :: AddressAny -> ThreatModel () Source #

Precondition that check that the original transaction has an input at a given address. Useful, for example, to ensure that you only consider transactions that trie to spend a script output from the script under test.

Validation

shouldValidate :: TxModifier -> ThreatModel () Source #

Check that a given modification of the original transaction validates. The modified transaction is printed in counterexample when this fails, or if it succeeds in a precondition and the test fails later.

shouldNotValidate :: TxModifier -> ThreatModel () Source #

Check that a given modification of the original transaction does not validate. The modified transaction is printed in counterexample when it does validate, or if it doesn't in a satisfied precondition and the test fails later.

data ValidityReport Source #

The result of validating a transaction. In case of failure, it includes a list of reasons.

Constructors

ValidityReport
Fields valid :: Bool errors :: [String]

Instances

Instances details

Eq ValidityReport Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel.Cardano.Api Methods (==) :: ValidityReport -> ValidityReport -> Bool Source # (/=) :: ValidityReport -> ValidityReport -> Bool Source #
Ord ValidityReport Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel.Cardano.Api Methods compare :: ValidityReport -> ValidityReport -> Ordering Source # (<) :: ValidityReport -> ValidityReport -> Bool Source # (<=) :: ValidityReport -> ValidityReport -> Bool Source # (>) :: ValidityReport -> ValidityReport -> Bool Source # (>=) :: ValidityReport -> ValidityReport -> Bool Source # max :: ValidityReport -> ValidityReport -> ValidityReport Source # min :: ValidityReport -> ValidityReport -> ValidityReport Source #
Show ValidityReport Source #
Instance details Defined in Test.QuickCheck.ContractModel.ThreatModel.Cardano.Api Methods showsPrec :: Int -> ValidityReport -> ShowS Source # show :: ValidityReport -> String Source # showList :: [ValidityReport] -> ShowS Source #

validate :: TxModifier -> ThreatModel ValidityReport Source #

The most low-level way to validate a modified transaction. In most cases shouldValidate and shouldNotValidate are preferred.

Querying the environment

getThreatModelEnv :: ThreatModel ThreatModelEnv Source #

Get the current context.

originalTx :: ThreatModel (Tx Era) Source #

Get the original transaction from the context.

getTxInputs :: ThreatModel [Input] Source #

Get the inputs from the original transaction.

getTxOutputs :: ThreatModel [Output] Source #

Get the outputs from the original transaction.

getRedeemer :: Input -> ThreatModel (Maybe Redeemer) Source #

Get the redeemer (if any) for an input of the original transaction.

Random generation

forAllTM :: Show a => Gen a -> (a -> [a]) -> ThreatModel a Source #

Generate a random value. Takes a QuickCheck generator and a shrink function.

pickAny :: Show a => [a] -> ThreatModel a Source #

Pick a random value from a list. Skips the test if the list is empty.

anySigner :: ThreatModel (Hash PaymentKey) Source #

Pick a random signer of the original transaction.

anyInputSuchThat :: (Input -> Bool) -> ThreatModel Input Source #

Pick a random input satisfying the given predicate.

anyOutputSuchThat :: (Output -> Bool) -> ThreatModel Output Source #

Pick a random output satisfying the given predicate.

Monitoring

counterexampleTM :: String -> ThreatModel () Source #

Print the given string in case this threat model fails. Threat model counterpart of the QuickCheck counterexample function.

tabulateTM :: String -> [String] -> ThreatModel () Source #

Threat model counterpart of QuickCheck's tabulate function.

collectTM :: Show a => a -> ThreatModel () Source #

Threat model counterpart of QuickCheck's collect function.

classifyTM :: Bool -> String -> ThreatModel () Source #

Threat model counterpart of QuickCheck's classify function.

monitorThreatModel :: (Property -> Property) -> ThreatModel () Source #

Monitoring that's shared between all transactions evaulated. Avoid this in favour of tabulateTM, collectTM and classifyTM when possible.

monitorLocalThreatModel :: (Property -> Property) -> ThreatModel () Source #

Monitoring that's local to the current transaction. Use counterexampleTM when possible.

Cardano API helpers

Some convenience functions making it easier to work with Cardano API.

projectAda :: Value -> Value Source #

Keep only the Ada part of a value.

leqValue :: Value -> Value -> Bool Source #

Check if a value is less or equal than another value.

Addresses

keyAddressAny :: Hash PaymentKey -> AddressAny Source #

Construct a public key address.

scriptAddressAny :: ScriptHash -> AddressAny Source #

Construct a script address.

isKeyAddressAny :: AddressAny -> Bool Source #

Check if an address is a public key address.

Datums

txOutDatum :: ScriptData -> TxOutDatum CtxTx Era Source #

Convert ScriptData to a Datum.

toScriptData :: ToData a => a -> ScriptData Source #

Convert a Haskell value to ScriptData for use as a Redeemer or convert to a Datum with txOutDatum.

datumOfTxOut :: TxOut ctx Era -> TxOutDatum ctx Era Source #

Get the datum from a transaction output.

Pretty printing

The framework already prints the original transaction and the results of validating modified transactions in counterexamples. To include more information you can use counterexampleTM with the functions below.

paragraph :: [String] -> String Source #

Format a list of strings as a paragraph. The structure of the list is not considered other than inserting whitespace between consecutive elements. Use with counterexampleTM when printing longer texts.

prettyAddress :: AddressAny -> Doc Source #

prettyValue :: Value -> Doc Source #

prettyDatum :: Datum -> Doc Source #

prettyInput :: Input -> Doc Source #

prettyOutput :: Output -> Doc Source #