| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
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
- 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
- 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 (TxAuxData 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
- class (EraTx era, AlonzoEraTxBody era, AlonzoEraTxWits era, AlonzoEraScript era) ⇒ AlonzoEraTx era
- isValidTxL ∷ AlonzoEraTx era ⇒ Lens' (Tx era) IsValid
- newtype IsValid = IsValid Bool
- evalTxExUnits ∷ (AlonzoEraTx era, EraUTxO era, EraPlutusContext era, ScriptsNeeded era ~ AlonzoScriptsNeeded era) ⇒ PParams era → Tx era → UTxO era → EpochInfo (Either Text) → SystemStart → RedeemerReport era
- type RedeemerReport era = Map (PlutusPurpose AsIx era) (Either (TransactionScriptFailure era) ExUnits)
- evalTxExUnitsWithLogs ∷ (AlonzoEraTx era, EraUTxO era, EraPlutusContext era, ScriptsNeeded era ~ AlonzoScriptsNeeded era) ⇒ PParams era → Tx era → UTxO era → EpochInfo (Either Text) → SystemStart → 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))
- | MissingDatum !DataHash
- | ValidationFailure !ExUnits !EvaluationError ![Text] !PlutusWithContext
- | UnknownTxIn !TxIn
- | InvalidTxIn !TxIn
- | IncompatibleBudget !ExBudget
- | NoCostModelInLedgerState !Language
- | ContextError !(ContextError era)
Documentation
Building and inspecting transaction bodies
module Cardano.Ledger.Api.Tx.Body
module Cardano.Ledger.Api.Tx.Cert
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, wireSizeTxF, validateNativeScript, getMinFeeTx, upgradeTx
auxDataTxL ∷ EraTx era ⇒ Lens' (Tx era) (StrictMaybe (TxAuxData era)) Source #
sizeTxF ∷ EraTx era ⇒ SimpleGetter (Tx era) Integer Source #
For fee calculation and estimations of impact on block space
Arguments
| ∷ EraTx era | |
| ⇒ PParams era | |
| → Tx era | |
| → Int | Size in bytes of reference scripts present in this transaction |
| → Coin |
Minimum fee calculation excluding witnesses
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.
Arguments
| ∷ EraUTxO era | |
| ⇒ UTxO era | All TxOuts available for this transaction. In other words |
| → 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
>>>let relevantUtxo = txInsFilter utxo (tx ^. bodyTxL . allInputsTxBodyF)>>>calcMinFeeTx relevantUtxo pp tx 5
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
Alonzo onwards
class (EraTx era, AlonzoEraTxBody era, AlonzoEraTxWits era, AlonzoEraScript era) ⇒ AlonzoEraTx era Source #
Minimal complete definition
Instances
| AlonzoEraTx AlonzoEra | |
Defined in Cardano.Ledger.Alonzo.Tx | |
isValidTxL ∷ AlonzoEraTx era ⇒ Lens' (Tx era) 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.
Execution units
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.
type RedeemerReport era = Map (PlutusPurpose AsIx era) (Either (TransactionScriptFailure era) ExUnits) Source #
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 Unlike |
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.
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
| |
| MissingDatum !DataHash | Missing datum. |
| ValidationFailure | Plutus evaluation error, for any version |
Fields
| |
| UnknownTxIn !TxIn | A redeemer points to a transaction input which is not present in the current UTxO. |
| InvalidTxIn !TxIn | 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 |
Instances
| (Era era, Show (TxCert era), Show (ContextError era), Show (PlutusScript era), Show (PlutusPurpose AsIx era), Show (PlutusPurpose AsItem era)) ⇒ Show (TransactionScriptFailure era) | |
Defined in Cardano.Ledger.Alonzo.Plutus.Evaluate | |
| (Era era, Eq (TxCert era), Eq (PlutusScript era), Eq (ContextError era), Eq (PlutusPurpose AsIx era), Eq (PlutusPurpose AsItem era)) ⇒ Eq (TransactionScriptFailure era) | |
Defined in Cardano.Ledger.Alonzo.Plutus.Evaluate Methods (==) ∷ TransactionScriptFailure era → TransactionScriptFailure era → Bool Source # (/=) ∷ TransactionScriptFailure era → TransactionScriptFailure era → Bool Source # | |