| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
Cooked.MockChain.BlockChain
Description
This modules provides a specification for our blockchain monads, in three layers:
- MonadBlockChainBalancing provides what's needing for balancing purposes
- MonadBlockChainWithoutValidation adds up remaining primitives without transaction validation
- MonadBlockChain concludes with the addition of transaction validation, thus modifying the internal index of outputs
In addition, you will find here many helpers functions which can be derived from the core definition of our blockchain.
Synopsis
- type Fee = Integer
- type CollateralIns = Set TxOutRef
- type Collaterals = Maybe (CollateralIns, Peer)
- type Utxos = [(TxOutRef, TxSkelOut)]
- data MockChainError
- = MCEValidationError ValidationPhase ValidationError
- | MCEUnbalanceable Peer Value
- | MCEMissingBalancingUser String
- | MCENoSuitableCollateral Integer Integer Value
- | MCEToCardanoError String ToCardanoError
- | MCEWrongReferenceScriptError TxOutRef ScriptHash (Maybe ScriptHash)
- | MCEUnknownOutRef TxOutRef
- | MCEPastSlot Slot Slot
- | MCEUnsupportedFeature String
- | FailWith String
- data MockChainLogEntry
- = MCLogSubmittedTxSkel TxSkel
- | MCLogAdjustedTxSkel TxSkel Fee Collaterals
- | MCLogNewTx TxId Integer
- | MCLogDiscardedUtxos Integer String
- | MCLogUnusedCollaterals (Either Peer CollateralIns)
- | MCLogAddedReferenceScript TxSkelRedeemer TxOutRef ScriptHash
- | MCLogAutoFilledWithdrawalAmount Credential Lovelace
- | MCLogAutoFilledConstitution ScriptHash
- | MCLogAdjustedTxSkelOut TxSkelOut Lovelace
- class (MonadFail m, MonadError MockChainError m) => MonadBlockChainBalancing m where
- getParams :: m Params
- utxosAt :: ToAddress a => a -> m Utxos
- txSkelOutByRef :: TxOutRef -> m TxSkelOut
- logEvent :: MockChainLogEntry -> m ()
- class MonadBlockChainBalancing m => MonadBlockChainWithoutValidation m where
- allUtxos :: m Utxos
- setParams :: Params -> m ()
- waitNSlots :: Integral i => i -> m Slot
- define :: ToHash a => String -> a -> m a
- setConstitutionScript :: ToVScript s => s -> m ()
- getConstitutionScript :: m (Maybe VScript)
- getCurrentReward :: ToCredential c => c -> m (Maybe Lovelace)
- class MonadBlockChainWithoutValidation m => MonadBlockChain m where
- validateTxSkel :: TxSkel -> m CardanoTx
- forceOutputs :: [TxSkelOut] -> m [TxOutRef]
- newtype AsTrans t (m :: Type -> Type) a = AsTrans {
- getTrans :: t m a
- currentMSRange :: MonadBlockChainWithoutValidation m => m (POSIXTime, POSIXTime)
- utxosFromCardanoTx :: MonadBlockChainBalancing m => CardanoTx -> m [(TxOutRef, TxSkelOut)]
- currentSlot :: MonadBlockChainWithoutValidation m => m Slot
- awaitSlot :: (MonadBlockChainWithoutValidation m, Integral i) => i -> m Slot
- getEnclosingSlot :: MonadBlockChainWithoutValidation m => POSIXTime -> m Slot
- awaitEnclosingSlot :: MonadBlockChainWithoutValidation m => POSIXTime -> m Slot
- waitNMSFromSlotLowerBound :: (MonadBlockChainWithoutValidation m, Integral i) => i -> m Slot
- waitNMSFromSlotUpperBound :: (MonadBlockChainWithoutValidation m, Integral i) => i -> m Slot
- slotRangeBefore :: MonadBlockChainWithoutValidation m => POSIXTime -> m SlotRange
- slotRangeAfter :: MonadBlockChainWithoutValidation m => POSIXTime -> m SlotRange
- slotToMSRange :: (MonadBlockChainWithoutValidation m, Integral i) => i -> m (POSIXTime, POSIXTime)
- txSkelInputScripts :: MonadBlockChainBalancing m => TxSkel -> m [VScript]
- txSkelInputValue :: MonadBlockChainBalancing m => TxSkel -> m Value
- lookupUtxos :: MonadBlockChainBalancing m => [TxOutRef] -> m (Map TxOutRef TxSkelOut)
- validateTxSkel' :: MonadBlockChain m => TxSkel -> m [TxOutRef]
- validateTxSkel_ :: MonadBlockChain m => TxSkel -> m ()
- txSkelDepositedValueInProposals :: MonadBlockChainBalancing m => TxSkel -> m Lovelace
- govActionDeposit :: MonadBlockChainBalancing m => m Lovelace
- defineM :: (MonadBlockChainWithoutValidation m, ToHash a) => String -> m a -> m a
- txSkelAllScripts :: MonadBlockChainBalancing m => TxSkel -> m [VScript]
- previewByRef :: (MonadBlockChainBalancing m, Is af An_AffineFold) => Optic' af is TxSkelOut c -> TxOutRef -> m (Maybe c)
- viewByRef :: (MonadBlockChainBalancing m, Is g A_Getter) => Optic' g is TxSkelOut c -> TxOutRef -> m c
- dRepDeposit :: MonadBlockChainBalancing m => m Lovelace
- stakeAddressDeposit :: MonadBlockChainBalancing m => m Lovelace
- stakePoolDeposit :: MonadBlockChainBalancing m => m Lovelace
- txSkelDepositedValueInCertificates :: MonadBlockChainBalancing m => TxSkel -> m Lovelace
Documentation
type CollateralIns = Set TxOutRef Source #
An alias for sets of utxos used as collateral inputs
type Collaterals = Maybe (CollateralIns, Peer) Source #
An alias for optional pairs of collateral inputs and return collateral peer
type Utxos = [(TxOutRef, TxSkelOut)] Source #
An alias for lists of utxos with their associated output
data MockChainError Source #
Errors that can be produced by the blockchain
Constructors
| MCEValidationError ValidationPhase ValidationError | Validation errors, either in Phase 1 or Phase 2 |
| MCEUnbalanceable Peer Value | The balancing user does not have enough funds |
| MCEMissingBalancingUser String | The balancing user is required but missing |
| MCENoSuitableCollateral Integer Integer Value | No suitable collateral could be associated with a skeleton |
| MCEToCardanoError String ToCardanoError | Translating a skeleton element to its Cardano counterpart failed |
| MCEWrongReferenceScriptError TxOutRef ScriptHash (Maybe ScriptHash) | The required reference script is missing from a witness utxo |
| MCEUnknownOutRef TxOutRef | A UTxO is missing from the mockchain state |
| MCEPastSlot Slot Slot | A jump in time would result in a past slot |
| MCEUnsupportedFeature String | An attempt to invoke an unsupported feature has been made |
| FailWith String | Used to provide |
Instances
data MockChainLogEntry Source #
This represents the specific events that should be logged when processing transactions. If a new kind of event arises, then a new constructor should be provided here.
Constructors
| MCLogSubmittedTxSkel TxSkel | Logging a Skeleton as it is submitted by the user. |
| MCLogAdjustedTxSkel TxSkel Fee Collaterals | Logging a Skeleton as it has been adjusted by the balancing mechanism, alongside fee, and possible collateral utxos and return collateral user. |
| MCLogNewTx TxId Integer | Logging the successful validation of a new transaction, with its id and number of produced outputs. |
| MCLogDiscardedUtxos Integer String | Logging the fact that utxos provided by the user for balancing have to be discarded for a specific reason. |
| MCLogUnusedCollaterals (Either Peer CollateralIns) | 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 user or a set of utxos to be used as collaterals. |
| MCLogAddedReferenceScript TxSkelRedeemer TxOutRef ScriptHash | Logging the automatic addition of a reference script |
| MCLogAutoFilledWithdrawalAmount Credential Lovelace | Logging the automatic addition of a withdrawal amount |
| MCLogAutoFilledConstitution ScriptHash | Logging the automatic addition of the constitution script |
| MCLogAdjustedTxSkelOut TxSkelOut Lovelace | Logging the automatic adjusment of a min ada amount |
Instances
| Show MockChainLogEntry Source # | |
Defined in Cooked.MockChain.BlockChain Methods showsPrec :: Int -> MockChainLogEntry -> ShowS # show :: MockChainLogEntry -> String # showList :: [MockChainLogEntry] -> ShowS # | |
| PrettyCooked (Contextualized MockChainLogEntry) Source # | This prints a |
Defined in Cooked.Pretty.MockChain | |
| PrettyCooked (Contextualized [MockChainLogEntry]) Source # | |
Defined in Cooked.Pretty.MockChain Methods prettyCookedOpt :: PrettyCookedOpts -> Contextualized [MockChainLogEntry] -> DocCooked Source # prettyCooked :: Contextualized [MockChainLogEntry] -> DocCooked Source # | |
class (MonadFail m, MonadError MockChainError m) => MonadBlockChainBalancing m where Source #
This is the first layer of our blockchain, which provides the minimal subset of primitives required to perform balancing.
Methods
getParams :: m Params Source #
Returns the emulator parameters, including protocol parameters
utxosAt :: ToAddress a => a -> m Utxos Source #
Returns a list of all UTxOs at a certain address.
txSkelOutByRef :: TxOutRef -> m TxSkelOut Source #
Returns an output given a reference to it. If the output does not exist,
throws a MCEUnknownOutRef error.
logEvent :: MockChainLogEntry -> m () Source #
Logs an event that occured during a BlockChain run
Instances
class MonadBlockChainBalancing m => MonadBlockChainWithoutValidation m where Source #
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.
Methods
Returns a list of all currently known outputs.
setParams :: Params -> m () Source #
Updates parameters
waitNSlots :: Integral i => i -> m Slot Source #
Wait a certain amount of slot. Throws MCEPastSlot if the input integer
is negative. Returns the slot after jumping in time.
define :: ToHash a => String -> a -> m a Source #
Binds a hashable quantity of type a to a variable in the mockchain,
while registering its alias for printing purposes.
setConstitutionScript :: ToVScript s => s -> m () Source #
Sets the current script to act as the official constitution script
getConstitutionScript :: m (Maybe VScript) Source #
Gets the current official constitution script
getCurrentReward :: ToCredential c => c -> m (Maybe Lovelace) Source #
Gets the current reward associated with a credential
Instances
class MonadBlockChainWithoutValidation m => MonadBlockChain m where Source #
The final layer of our blockchain, adding transaction validation to the mix. This is the only primitive that actually modifies the ledger state.
Methods
validateTxSkel :: TxSkel -> m CardanoTx Source #
Generates, balances and validates a transaction from a skeleton. It returns the validated transaction and updates the state of the blockchain.
forceOutputs :: [TxSkelOut] -> m [TxOutRef] Source #
Forces the generation of utxos corresponding to certain TxSkelOut
Instances
newtype AsTrans t (m :: Type -> Type) a Source #
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.
Instances
currentMSRange :: MonadBlockChainWithoutValidation m => m (POSIXTime, POSIXTime) Source #
Returns the closed ms interval corresponding to the current slot
utxosFromCardanoTx :: MonadBlockChainBalancing m => CardanoTx -> m [(TxOutRef, TxSkelOut)] Source #
currentSlot :: MonadBlockChainWithoutValidation m => m Slot Source #
Returns the current slot number
awaitSlot :: (MonadBlockChainWithoutValidation m, Integral i) => i -> m Slot Source #
Wait for a certain slot, or throws an error if the slot is already past
getEnclosingSlot :: MonadBlockChainWithoutValidation m => POSIXTime -> m Slot Source #
Return the slot that contains the given time. See slotToMSRange for
some satisfied equational properties.
awaitEnclosingSlot :: MonadBlockChainWithoutValidation m => POSIXTime -> m Slot Source #
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.
waitNMSFromSlotLowerBound :: (MonadBlockChainWithoutValidation m, Integral i) => i -> m Slot Source #
Wait a given number of ms from the lower bound of the current slot and returns the current slot after waiting.
waitNMSFromSlotUpperBound :: (MonadBlockChainWithoutValidation m, Integral i) => i -> m Slot Source #
Wait a given number of ms from the upper bound of the current slot and returns the current slot after waiting.
slotRangeBefore :: MonadBlockChainWithoutValidation m => POSIXTime -> m SlotRange Source #
The infinite range of slots ending before or at the given time
slotRangeAfter :: MonadBlockChainWithoutValidation m => POSIXTime -> m SlotRange Source #
The infinite range of slots starting after or at the given time
slotToMSRange :: (MonadBlockChainWithoutValidation m, Integral i) => i -> m (POSIXTime, POSIXTime) Source #
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
txSkelInputScripts :: MonadBlockChainBalancing m => TxSkel -> m [VScript] Source #
Returns all scripts which guard transaction inputs
txSkelInputValue :: MonadBlockChainBalancing m => TxSkel -> m Value Source #
look up the UTxOs the transaction consumes, and sum their values.
lookupUtxos :: MonadBlockChainBalancing m => [TxOutRef] -> m (Map TxOutRef TxSkelOut) Source #
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.
validateTxSkel' :: MonadBlockChain m => TxSkel -> m [TxOutRef] Source #
Validates a skeleton, and retuns the ordered list of produced output references
validateTxSkel_ :: MonadBlockChain m => TxSkel -> m () Source #
Validates a skeleton, and erases the outputs
txSkelDepositedValueInProposals :: MonadBlockChainBalancing m => TxSkel -> m Lovelace Source #
Retrieves the total amount of lovelace deposited in proposals in this
skeleton (equal to govActionDeposit times the number of proposals).
govActionDeposit :: MonadBlockChainBalancing m => m Lovelace Source #
Retrieves the required governance action deposit amount
defineM :: (MonadBlockChainWithoutValidation m, ToHash a) => String -> m a -> m a Source #
Like define, but binds the result of a monadic computation instead
txSkelAllScripts :: MonadBlockChainBalancing m => TxSkel -> m [VScript] Source #
Returns all scripts involved in this TxSkel
previewByRef :: (MonadBlockChainBalancing m, Is af An_AffineFold) => Optic' af is TxSkelOut c -> TxOutRef -> m (Maybe c) Source #
Retrieves an output and previews a specific element out of it
viewByRef :: (MonadBlockChainBalancing m, Is g A_Getter) => Optic' g is TxSkelOut c -> TxOutRef -> m c Source #
Retrieves an output and views a specific element out of it
dRepDeposit :: MonadBlockChainBalancing m => m Lovelace Source #
Retrieves the required drep deposit amount
stakeAddressDeposit :: MonadBlockChainBalancing m => m Lovelace Source #
Retrieves the required stake address deposit amount
stakePoolDeposit :: MonadBlockChainBalancing m => m Lovelace Source #
Retrieves the required stake pool deposit amount
txSkelDepositedValueInCertificates :: MonadBlockChainBalancing m => TxSkel -> m Lovelace Source #
Retrieves the total amount of lovelace deposited in certificates in this skeleton. Note that unregistering a staking address or a dRep lead to a negative deposit (a withdrawal, in fact) which means this function can return a negative amount of lovelace, which is intended. The deposited amounts are dictated by the current protocol parameters, and computed as such.