cardano-ledger-api-1.9.2.2: Public API for the cardano ledger codebase
Safe HaskellSafe-Inferred
LanguageHaskell2010

Cardano.Ledger.Api.Tx

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

Documentation

Building and inspecting transaction bodies

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.

Associated Types

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

mkBasicTxEraTx era ⇒ TxBody era → Tx era Source #

bodyTxLEraTx era ⇒ Lens' (Tx era) (TxBody era) Source #

witsTxLEraTx era ⇒ Lens' (Tx era) (TxWits era) Source #

auxDataTxLEraTx era ⇒ Lens' (Tx era) (StrictMaybe (AuxiliaryData era)) 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.

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

txIdTxEraTx 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

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

Generic IsValid 
Instance details

Defined in Cardano.Ledger.Alonzo.Tx

Associated Types

type Rep IsValidTypeType Source #

Methods

fromIsValidRep IsValid x Source #

toRep IsValid x → IsValid Source #

Show IsValid 
Instance details

Defined in Cardano.Ledger.Alonzo.Tx

ToCBOR IsValid 
Instance details

Defined in Cardano.Ledger.Alonzo.Tx

Methods

toCBORIsValidEncoding Source #

encodedSizeExpr ∷ (∀ t. ToCBOR t ⇒ Proxy t → Size) → Proxy IsValidSize Source #

encodedListSizeExpr ∷ (∀ t. ToCBOR t ⇒ Proxy t → Size) → Proxy [IsValid] → Size Source #

DecCBOR IsValid 
Instance details

Defined in Cardano.Ledger.Alonzo.Tx

EncCBOR IsValid 
Instance details

Defined in Cardano.Ledger.Alonzo.Tx

Methods

encCBORIsValidEncoding Source #

encodedSizeExpr ∷ (∀ t. EncCBOR t ⇒ Proxy t → Size) → Proxy IsValidSize Source #

encodedListSizeExpr ∷ (∀ t. EncCBOR t ⇒ Proxy t → Size) → Proxy [IsValid] → Size Source #

NFData IsValid 
Instance details

Defined in Cardano.Ledger.Alonzo.Tx

Methods

rnfIsValid → () Source #

Eq IsValid 
Instance details

Defined in Cardano.Ledger.Alonzo.Tx

Methods

(==)IsValidIsValidBool Source #

(/=)IsValidIsValidBool Source #

NoThunks IsValid 
Instance details

Defined in Cardano.Ledger.Alonzo.Tx

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.10.0.1-inplace" 'True) (C1 ('MetaCons "IsValid" 'PrefixI 'False) (S1 ('MetaSel ('NothingMaybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool)))

Execution units

evalTxExUnits Source #

Arguments

∷ (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.

RedeemerReport era

We return a map from redeemer pointers to either a failure or a sufficient execution budget.

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.

evalTxExUnitsWithLogs Source #

Arguments

∷ (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.

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.

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

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

MissingDatum !(DataHash (EraCrypto era))

Missing datum.

ValidationFailure

Plutus evaluation error, for any version

Fields

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

ContextError !(ContextError era)

Error that can happen during plutus context translation