Safe Haskell	Safe-Inferred
Language	Haskell2010

Cardano.Ledger.Api.Tx

Contents

Shelley onwards
Alonzo onwards
- Execution units

Description

Transaction building and inspecting relies heavily on lenses (microlens). Therefore, some familiarity with those is necessary. However, you can probably go a long way by simply looking at the examples and try to go from there.

Let's start by defining the GHC extensions and imports.

>>> :set -XScopedTypeVariables
>>> import Test.QuickCheck
>>> import qualified Data.Sequence.Strict as StrictSeq
>>> import Cardano.Ledger.Api.Era (Babbage)
>>> import Lens.Micro
>>> import Test.Cardano.Ledger.Babbage.Arbitrary ()

Here's an example on how to build a Babbage era unbalanced transaction containing a single transaction output using the provided interface.

>>> :{
quickCheck $ \(txOut :: TxOut Babbage) ->
    let
        -- Defining a Babbage era transaction body with a single random transaction output
        txBody = mkBasicTxBody
               & outputsTxBodyL <>~ StrictSeq.singleton txOut
        -- Defining a basic transaction with our transaction body
        tx = mkBasicTx txBody
     in
        -- We verify that the transaction's outputs contains our single random output
        tx ^. bodyTxL . outputsTxBodyL == StrictSeq.singleton txOut
:}
+++ OK, passed 100 tests.

Synopsis

module Cardano.Ledger.Api.Tx.Body
module Cardano.Ledger.Api.Tx.Cert
module Cardano.Ledger.Api.Tx.AuxData
module Cardano.Ledger.Api.Tx.Wits
class (EraTxBody era, EraTxWits era, EraTxAuxData era, EraPParams era, NoThunks (Tx era), DecCBOR (Annotator (Tx era)), EncCBOR (Tx era), ToCBOR (Tx era), Show (Tx era), Eq (Tx era), EqRaw (Tx era)) ⇒ EraTx era where
- type Tx era = (r ∷ Type) | r → era
mkBasicTx ∷ EraTx era ⇒ TxBody era → Tx era
bodyTxL ∷ EraTx era ⇒ Lens' (Tx era) (TxBody era)
witsTxL ∷ EraTx era ⇒ Lens' (Tx era) (TxWits era)
auxDataTxL ∷ EraTx era ⇒ Lens' (Tx era) (StrictMaybe (AuxiliaryData era))
sizeTxF ∷ EraTx era ⇒ SimpleGetter (Tx era) Integer
getMinFeeTx ∷ EraTx era ⇒ PParams era → Tx era → Int → Coin
setMinFeeTx ∷ EraTx era ⇒ PParams era → Tx era → Int → Tx era
setMinFeeTxUtxo ∷ EraUTxO era ⇒ PParams era → Tx era → UTxO era → Tx era
calcMinFeeTx ∷ EraUTxO era ⇒ UTxO era → PParams era → Tx era → Int → Coin
estimateMinFeeTx ∷ EraTx era ⇒ PParams era → Tx era → Int → Int → Int → Coin
txIdTx ∷ EraTx era ⇒ Tx era → TxId (EraCrypto era)
class (EraTx era, AlonzoEraTxBody era, AlonzoEraTxWits era, AlonzoEraScript era) ⇒ AlonzoEraTx era
isValidTxL ∷ AlonzoEraTx era ⇒ Lens' (Tx era) IsValid
newtype IsValid = IsValid Bool
evalTxExUnits ∷ ∀ era. (AlonzoEraTx era, EraUTxO era, EraPlutusContext era, ScriptsNeeded era ~ AlonzoScriptsNeeded era) ⇒ PParams era → Tx era → UTxO era → EpochInfo (Either Text) → SystemStart → Either (ContextError era) (RedeemerReport era)
type RedeemerReport era = Map (PlutusPurpose AsIx era) (Either (TransactionScriptFailure era) ExUnits)
evalTxExUnitsWithLogs ∷ ∀ era. (AlonzoEraTx era, EraUTxO era, EraPlutusContext era, ScriptsNeeded era ~ AlonzoScriptsNeeded era) ⇒ PParams era → Tx era → UTxO era → EpochInfo (Either Text) → SystemStart → Either (ContextError era) (RedeemerReportWithLogs era)
type RedeemerReportWithLogs era = Map (PlutusPurpose AsIx era) (Either (TransactionScriptFailure era) ([Text], ExUnits))
data TransactionScriptFailure era
- = RedeemerPointsToUnknownScriptHash !(PlutusPurpose AsIx era)
- | MissingScript !(PlutusPurpose AsIx era) !(Map (PlutusPurpose AsIx era) (PlutusPurpose AsItem era, Maybe (PlutusScript era), ScriptHash (EraCrypto era)))
- | MissingDatum !(DataHash (EraCrypto era))
- | ValidationFailure !ExUnits !EvaluationError ![Text] !(PlutusWithContext (EraCrypto era))
- | UnknownTxIn !(TxIn (EraCrypto era))
- | InvalidTxIn !(TxIn (EraCrypto era))
- | IncompatibleBudget !ExBudget
- | NoCostModelInLedgerState !Language

Documentation

Building and inspecting transaction bodies

module Cardano.Ledger.Api.Tx.Body

module Cardano.Ledger.Api.Tx.Cert

module Cardano.Ledger.Api.Tx.AuxData

module Cardano.Ledger.Api.Tx.Wits

Shelley onwards

class (EraTxBody era, EraTxWits era, EraTxAuxData era, EraPParams era, NoThunks (Tx era), DecCBOR (Annotator (Tx era)), EncCBOR (Tx era), ToCBOR (Tx era), Show (Tx era), Eq (Tx era), EqRaw (Tx era)) ⇒ EraTx era Source #

A transaction.

Minimal complete definition

mkBasicTx, bodyTxL, witsTxL, auxDataTxL, sizeTxF, validateNativeScript, getMinFeeTx, upgradeTx

Associated Types

type Tx era = (r ∷ Type) | r → era Source #

mkBasicTx ∷ EraTx era ⇒ TxBody era → Tx era Source #

bodyTxL ∷ EraTx era ⇒ Lens' (Tx era) (TxBody era) Source #

witsTxL ∷ EraTx era ⇒ Lens' (Tx era) (TxWits era) Source #

auxDataTxL ∷ EraTx era ⇒ Lens' (Tx era) (StrictMaybe (AuxiliaryData era)) Source #

sizeTxF ∷ EraTx era ⇒ SimpleGetter (Tx era) Integer Source #

getMinFeeTx Source #

Arguments

∷ EraTx era
⇒ PParams era
→ Tx era
→ Int	Size in bytes of reference scripts present in this transaction
→ Coin

Minimum fee calculation excluding witnesses

setMinFeeTx Source #

Arguments

∷ EraTx era
⇒ PParams era
→ Tx era
→ Int	Size in bytes of reference scripts present in this transaction
→ Tx era

Calculate and update the fee in the transaction until it has the smallest possible value according to the settings in the protocol parameters.

This function potentially changes the feeTxBodyL field of the TxBody, as such it affects the hash of the body, which consequently invalidates all of the signature in the attached witnesses.

setMinFeeTxUtxo ∷ EraUTxO era ⇒ PParams era → Tx era → UTxO era → Tx era Source #

calcMinFeeTx Source #

Arguments

∷ EraUTxO era
⇒ UTxO era	All TxOuts available for this transaction. In other words `TxIn`s produced by `allInputsTxBodyF` should be present in this `UTxO` map, however this is not checked.
→ PParams era	The current protocol parameters.
→ Tx era	The transaction.
→ Int	Number of extra KeyHash witnesses that will be supplied for satisfying native scripts. It is impossible to know how many of these is required without knowing the actual witnesses supplied and the time when the transaction will be submitted. Therefore we put this burden on the user. This number can also be used to specify all of the redundant extra key witnesses that will be supplied.
→ Coin	The required minimum fee.

This is a more accurate version estimateMinFeeTx that looks into transaction and figures out how many and what kind of key witnesses this transaction needs. It requires access to the portion of the UTxO that is relevant for this transaction. The only type of witnesses that it cannot figure out reliably is the witnesses needed for satisfying native scripts included in the transaction. For this reason number of witnesses needed for native scripts must be supplied as an extra argument.

Example

Expand

>>> let relevantUtxo = txInsFilter utxo (tx ^. bodyTxL . allInputsTxBodyF)
>>> calcMinFeeTx relevantUtxo pp tx 5

estimateMinFeeTx Source #

Arguments

∷ EraTx era
⇒ PParams era	The current protocol parameters.
→ Tx era	The transaction.
→ Int	The number of key witnesses still to be added to the transaction.
→ Int	The number of Byron key witnesses still to be added to the transaction.
→ Int	The total size in bytes of reference scripts
→ Coin	The required minimum fee.

Estimate a minimum transaction fee for a transaction that does not yet have all of the VKey witnesses. This calculation is not very accurate in estimating Byron witnesses, but it should work for the most part. If you have access to UTxO necessary for the transaction that it is better and easier to use calcMinFeeTx instead.

Since: cardano-ledger-core-1.8.0

txIdTx ∷ EraTx era ⇒ Tx era → TxId (EraCrypto era) Source #

Alonzo onwards

class (EraTx era, AlonzoEraTxBody era, AlonzoEraTxWits era, AlonzoEraScript era) ⇒ AlonzoEraTx era Source #

Minimal complete definition

isValidTxL

Instances

Instances details

Crypto c ⇒ AlonzoEraTx (AlonzoEra c)
Instance details Defined in Cardano.Ledger.Alonzo.Tx Methods isValidTxL ∷ Lens' (Tx (AlonzoEra c)) IsValid Source #

isValidTxL ∷ AlonzoEraTx era ⇒ Lens' (Tx era) IsValid Source #

newtype IsValid Source #

Tag indicating whether non-native scripts in this transaction are expected to validate. This is added by the block creator when constructing the block.

Constructors

IsValid Bool

Instances

Instances details

ToJSON IsValid
Instance details Defined in Cardano.Ledger.Alonzo.Tx Methods toJSON ∷ IsValid → Value Source # toEncoding ∷ IsValid → Encoding Source # toJSONList ∷ [IsValid] → Value Source # toEncodingList ∷ [IsValid] → Encoding Source # omitField ∷ IsValid → Bool Source #
Generic IsValid
Instance details Defined in Cardano.Ledger.Alonzo.Tx Associated Types type Rep IsValid ∷ Type → Type Source # Methods from ∷ IsValid → Rep IsValid x Source # to ∷ Rep IsValid x → IsValid Source #
Show IsValid
Instance details Defined in Cardano.Ledger.Alonzo.Tx Methods showsPrec ∷ Int → IsValid → ShowS Source # show ∷ IsValid → String Source # showList ∷ [IsValid] → ShowS Source #
ToCBOR IsValid
Instance details Defined in Cardano.Ledger.Alonzo.Tx Methods toCBOR ∷ IsValid → Encoding Source # encodedSizeExpr ∷ (∀ t. ToCBOR t ⇒ Proxy t → Size) → Proxy IsValid → Size Source # encodedListSizeExpr ∷ (∀ t. ToCBOR t ⇒ Proxy t → Size) → Proxy [IsValid] → Size Source #
DecCBOR IsValid
Instance details Defined in Cardano.Ledger.Alonzo.Tx Methods decCBOR ∷ Decoder s IsValid Source # dropCBOR ∷ Proxy IsValid → Decoder s () Source # label ∷ Proxy IsValid → Text Source #
EncCBOR IsValid
Instance details Defined in Cardano.Ledger.Alonzo.Tx Methods encCBOR ∷ IsValid → Encoding Source # encodedSizeExpr ∷ (∀ t. EncCBOR t ⇒ Proxy t → Size) → Proxy IsValid → Size Source # encodedListSizeExpr ∷ (∀ t. EncCBOR t ⇒ Proxy t → Size) → Proxy [IsValid] → Size Source #
NFData IsValid
Instance details Defined in Cardano.Ledger.Alonzo.Tx Methods rnf ∷ IsValid → () Source #
Eq IsValid
Instance details Defined in Cardano.Ledger.Alonzo.Tx Methods (==) ∷ IsValid → IsValid → Bool Source # (/=) ∷ IsValid → IsValid → Bool Source #
NoThunks IsValid
Instance details Defined in Cardano.Ledger.Alonzo.Tx Methods noThunks ∷ Context → IsValid → IO (Maybe ThunkInfo) Source # wNoThunks ∷ Context → IsValid → IO (Maybe ThunkInfo) Source # showTypeOf ∷ Proxy IsValid → String Source #
type Rep IsValid
Instance details Defined in Cardano.Ledger.Alonzo.Tx type Rep IsValid = D1 ('MetaData "IsValid" "Cardano.Ledger.Alonzo.Tx" "cardano-ledger-alonzo-1.8.0.0-inplace" 'True) (C1 ('MetaCons "IsValid" 'PrefixI 'False) (S1 ('MetaSel ('Nothing ∷ Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool)))

Execution units

evalTxExUnits Source #

Arguments

∷ ∀ era. (AlonzoEraTx era, EraUTxO era, EraPlutusContext era, ScriptsNeeded era ~ AlonzoScriptsNeeded era)
⇒ PParams era
→ Tx era	The transaction.
→ UTxO era	The current UTxO set (or the relevant portion for the transaction).
→ EpochInfo (Either Text)	The epoch info, used to translate slots to POSIX time for plutus.
→ SystemStart	The start time of the given block chain.
→ Either (ContextError era) (RedeemerReport era)	We return a map from redeemer pointers to either a failure or a sufficient execution budget. Otherwise, we return a `TranslationError` manifesting from failed attempts to construct a valid execution context for the given transaction.

Evaluate the execution budgets needed for all the redeemers in a given transaction. If a redeemer is invalid, a failure is returned instead.

The execution budgets in the supplied transaction are completely ignored. The results of evalTxExUnitsWithLogs are intended to replace them.

type RedeemerReport era = Map (PlutusPurpose AsIx era) (Either (TransactionScriptFailure era) ExUnits) Source #

evalTxExUnitsWithLogs Source #

Arguments

∷ ∀ era. (AlonzoEraTx era, EraUTxO era, EraPlutusContext era, ScriptsNeeded era ~ AlonzoScriptsNeeded era)
⇒ PParams era
→ Tx era	The transaction.
→ UTxO era	The current UTxO set (or the relevant portion for the transaction).
→ EpochInfo (Either Text)	The epoch info, used to translate slots to POSIX time for plutus.
→ SystemStart	The start time of the given block chain.
→ Either (ContextError era) (RedeemerReportWithLogs era)	We return a map from redeemer pointers to either a failure or a sufficient execution budget with logs of the script. Otherwise, we return a `TranslationError` manifesting from failed attempts to construct a valid execution context for the given transaction. Unlike `evalTxExUnits`, this function also returns evaluation logs, useful for debugging.

Evaluate the execution budgets needed for all the redeemers in a given transaction. If a redeemer is invalid, a failure is returned instead.

The execution budgets in the supplied transaction are completely ignored. The results of evalTxExUnitsWithLogs are intended to replace them.

type RedeemerReportWithLogs era = Map (PlutusPurpose AsIx era) (Either (TransactionScriptFailure era) ([Text], ExUnits)) Source #

data TransactionScriptFailure era Source #

Script failures that can be returned by evalTxExUnitsWithLogs.

Constructors

RedeemerPointsToUnknownScriptHash !(PlutusPurpose AsIx era)	A redeemer was supplied which points to a script hash which we cannot connect to a Plutus script.
MissingScript	Missing redeemer.
Fields !(PlutusPurpose AsIx era) Redeemer pointer which cannot be resolved !(Map (PlutusPurpose AsIx era) (PlutusPurpose AsItem era, Maybe (PlutusScript era), ScriptHash (EraCrypto era))) Map of pointers which can be resolved together with PlutusScripts and their respective contexts
MissingDatum !(DataHash (EraCrypto era))	Missing datum.
ValidationFailure	Plutus evaluation error, for any version
Fields !ExUnits Supplied execution units in the transaction, which were ignored for calculating the actual execution units. !EvaluationError ![Text] !(PlutusWithContext (EraCrypto era))
UnknownTxIn !(TxIn (EraCrypto era))	A redeemer points to a transaction input which is not present in the current UTxO.
InvalidTxIn !(TxIn (EraCrypto era))	A redeemer points to a transaction input which is not plutus locked.
IncompatibleBudget !ExBudget	The execution budget that was calculated by the Plutus evaluator is out of bounds.
NoCostModelInLedgerState !Language	There was no cost model for a given version of Plutus in the ledger state

Instances

Instances details

(Era era, Show (TxCert era), Show (PlutusScript era), Show (PlutusPurpose AsIx era), Show (PlutusPurpose AsItem era)) ⇒ Show (TransactionScriptFailure era) Source #
Instance details Defined in Cardano.Ledger.Api.Scripts.ExUnits Methods showsPrec ∷ Int → TransactionScriptFailure era → ShowS Source # show ∷ TransactionScriptFailure era → String Source # showList ∷ [TransactionScriptFailure era] → ShowS Source #
(Era era, Eq (TxCert era), Eq (PlutusScript era), Eq (PlutusPurpose AsIx era), Eq (PlutusPurpose AsItem era)) ⇒ Eq (TransactionScriptFailure era) Source #
Instance details Defined in Cardano.Ledger.Api.Scripts.ExUnits Methods (==) ∷ TransactionScriptFailure era → TransactionScriptFailure era → Bool Source # (/=) ∷ TransactionScriptFailure era → TransactionScriptFailure era → Bool Source #