atlas-cardano-0.5.0: Application backend for Plutus smart contracts on Cardano
Copyright(c) 2023 GYELD GMBH
LicenseApache 2.0
Maintainer[email protected]
Stabilitydevelop
Safe HaskellSafe-Inferred
LanguageGHC2021

GeniusYield.Transaction

Description

Balancing algorithm.

Inputs:

  • Transaction inputs
  • Transaction outputs
  • Transaction minted value

Additionally:

  • Set of additional UTxOs which can be spent
  • Collateral UTxO
  • Change address

The algorithm should produce sets of inputs and outputs such the total value is input + minted = outputs.

The algorithms used to select inputs & produce change outputs are defined in CoinSelection.

Each output should be big enough (contain enough ADA, calculateMinimumUTxO). Algorithm may adjust them to include additional value.

There are also transacton fees which should also be taken into account. We over-approximate the fees, and let makeTransactionBodyAutoBalance balance fees. (We can be more precise here, and only slightly over-approximate, but cardano-api doesn't provide a handy helpers to fill in execution units).

We make the algorithm iterative over the fee over-approximation. In particular, we start off with a small over-approximation, and if tx finalization fails, we increase it. The very first success is returned. Any over approximation (above the actual required fees), leads to generation of change output (besides those generated by coin selection) by makeTransactionBodyAutoBalance. This new change output may fail minimum ada requirement, in which case we iterate with increased fee approximate.

Collateral input is needed when scripts are executed, i.e. transaction mints tokens or consumes script outputs.

See evaluateTransactionBalance and makeTransactionBodyAutoBalance (this function balances ADA only and doesn't add inputs, i.e. it calculates the ADA change).

Synopsis

Top level build interface

data GYBuildTxEnv #

A container for various network parameters, and user wallet information, used by balancer.

buildUnsignedTxBody #

Arguments

∷ ∀ m v. (HasCallStack, MonadRandom m) 
GYBuildTxEnv 
GYCoinSelectionStrategy 
→ [GYTxInDetailed v] 
→ [GYTxOut v] 
GYUTxOs

reference inputs

Maybe (GYValue, [(GYMintScript v, GYRedeemer)])

minted values

→ [GYTxWdrl v]

withdrawals

→ [GYTxCert v]

certificates

Maybe GYSlot 
Maybe GYSlot 
Set GYPubKeyHash 
Maybe GYTxMetadata 
→ m (Either BuildTxException GYTxBody) 

Pure interface to build the transaction body given necessary information.

data BuildTxException #

Constructors

BuildTxBalancingError !BalancingError 
BuildTxBodyErrorAutoBalance !TxBodyErrorAutoBalance 
BuildTxPPConversionError !ProtocolParametersConversionError 
BuildTxMissingMaxExUnitsParam

Missing max ex units in protocol params

BuildTxExUnitsTooBig

Execution units required is higher than the maximum as specified by protocol params.

Fields

  • (Natural, Natural)

    Tuple of maximum execution steps & memory as given by protocol parameters.

  • (Natural, Natural)

    Tuple of execution steps & memory as taken by built transaction.

BuildTxSizeTooBig

Transaction size is higher than the maximum as specified by protocol params.

Fields

  • !Natural

    Maximum size as specified by protocol parameters.

  • !Natural

    Size our built transaction took.

BuildTxCollateralShortFall

Shortfall (in collateral inputs) for collateral requirement.

Fields

  • !Natural

    Transaction collateral requirement.

  • !Natural

    Lovelaces in given collateral UTxO.

BuildTxNoSuitableCollateral

Couldn't find a UTxO to use as collateral.

BuildTxCborSimplificationError !CborSimplificationError 
BuildTxCollapseExtraOutError !TxBodyError 

data GYCoinSelectionStrategy #

Instances

Instances details
Bounded GYCoinSelectionStrategy # 
Instance details

Defined in GeniusYield.Transaction.CoinSelection

Enum GYCoinSelectionStrategy # 
Instance details

Defined in GeniusYield.Transaction.CoinSelection

Show GYCoinSelectionStrategy # 
Instance details

Defined in GeniusYield.Transaction.CoinSelection

Eq GYCoinSelectionStrategy # 
Instance details

Defined in GeniusYield.Transaction.CoinSelection

Balancing only

balanceTxStep #

Arguments

∷ (HasCallStack, MonadRandom m) 
GYBuildTxEnv 
Maybe (GYValue, [(GYMintScript v, GYRedeemer)])

minting

→ [GYTxWdrl v]

withdrawals

→ [GYTxCert v]

certificates

→ [GYTxInDetailed v]

transaction inputs

→ [GYTxOut v]

transaction outputs

GYCoinSelectionStrategy

Coin selection strategy to use

Natural

extra lovelace to look for on top of output value

→ m (Either BalancingError ([GYTxInDetailed v], GYUTxOs, [GYTxOut v])) 

An independent "step" of the balancing algorithm.

This step is meant to be run with different extraLovelace values. If the extraLovelace amount is too small, there will not be enough ada to pay for the final fees + min deposits, when finalizing the tx with finalizeGYBalancedTx. If such is the case, balanceTxStep should be called again with a higher extraLovelace amount.

Utility type

data GYTxInDetailed v #

A further detailed version of GYTxIn, containing all information about a UTxO.

Instances

Instances details
Show (GYTxInDetailed v) # 
Instance details

Defined in GeniusYield.Transaction.Common

Eq (GYTxInDetailed v) # 
Instance details

Defined in GeniusYield.Transaction.Common