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



Balancing algorithm.


  • Transaction inputs
  • Transaction outputs
  • Transaction minted value


  • 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).


Top level build interface

data GYBuildTxEnv #

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

buildUnsignedTxBody #


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

reference inputs

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

minted values

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

Pure interface to build the transaction body given necessary information.

data BuildTxException #


BuildTxBalancingError !BalancingError 
BuildTxBodyErrorAutoBalance !TxBodyErrorAutoBalance 
BuildTxPPConversionError !ProtocolParametersConversionError 

Missing max ex units in protocol params


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


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


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


  • !Natural

    Maximum size as specified by protocol parameters.

  • !Natural

    Size our built transaction took.


Shortfall (in collateral inputs) for collateral requirement.


  • !Natural

    Transaction collateral requirement.

  • !Natural

    Lovelaces in given collateral UTxO.


Couldn't find a UTxO to use as collateral.

BuildTxCborSimplificationError !CborSimplificationError 
BuildTxCollapseExtraOutError !TxBodyError 

Balancing only

balanceTxStep #


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


→ [GYTxInDetailed v]

transaction inputs

→ [GYTxOut v]

transaction outputs


Coin selection strategy to use


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 details
Show (GYTxInDetailed v) # 
Instance details

Defined in GeniusYield.Transaction.Common

Eq (GYTxInDetailed v) # 
Instance details

Defined in GeniusYield.Transaction.Common