atlas-0.1.0.0: Application backend for Plutus smart contracts on Cardano
Copyright(c) 2023 GYELD GMBH
LicenseApache 2.0
Maintainersupport@geniusyield.co
Stabilitydevelop
Safe HaskellNone
LanguageHaskell2010

GeniusYield.Transaction

Description

Balancing algorithm.

Inputs:

  • Transaction inputs
  • Transaction outputs
  • Transaction minted value

Additionally:

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

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

The algorithm used to select inputs is 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.

The algorithm should add additional inputs so all inputs have enough value for all (adjusted) outputs.

As usually inputs and outputs don't match equally, the left-over inputs are sent to change address. This output should also be adjusted. (TODO: is it enough to send only non-ADA there?)

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). This also means that currently, it is unable to put non-ada tokens as return collateral output, so as of now we only support ada only collateral utxo.

Synopsis

Top level build interface

data GYBuildTxEnv #

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

Constructors

GYBuildTxEnv 

Fields

buildUnsignedTxBody #

Arguments

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

reference inputs

Maybe (GYValue, [(Some GYMintingPolicy, 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 #

Constructors

BuildTxBalancingError !BalancingError 
BuildTxBodyErrorAutoBalance !TxBodyErrorAutoBalance 
BuildTxMissingMaxExUnitsParam

Missing max ex units in protocol params

BuildTxExUnitsTooBig

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

BuildTxSizeTooBig

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

Balancing only

balanceTxStep #

Arguments

∷ (HasCallStack, MonadRandom m) 
GYBuildTxEnv 
Bool

use inline datums

Maybe (GYValue, [(Some GYMintingPolicy, GYRedeemer)])

minting

→ [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
Eq (GYTxInDetailed v) # 
Instance details

Defined in GeniusYield.Transaction.Common

Show (GYTxInDetailed v) # 
Instance details

Defined in GeniusYield.Transaction.Common