Copyright | (c) 2023 GYELD GMBH |
---|---|
License | Apache 2.0 |
Maintainer | [email protected] |
Stability | develop |
Safe Haskell | Safe-Inferred |
Language | GHC2021 |
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
- data GYBuildTxEnv = GYBuildTxEnv {}
- buildUnsignedTxBody ∷ ∀ m v. (HasCallStack, MonadRandom m) ⇒ GYBuildTxEnv → GYCoinSelectionStrategy → [GYTxInDetailed v] → [GYTxOut v] → GYUTxOs → Maybe (GYValue, [(GYMintScript v, GYRedeemer)]) → Maybe GYSlot → Maybe GYSlot → Set GYPubKeyHash → m (Either BuildTxException GYTxBody)
- data BuildTxException
- = BuildTxBalancingError !BalancingError
- | BuildTxBodyErrorAutoBalance !TxBodyErrorAutoBalance
- | BuildTxPPConversionError !ProtocolParametersConversionError
- | BuildTxMissingMaxExUnitsParam
- | BuildTxExUnitsTooBig (Natural, Natural) (Natural, Natural)
- | BuildTxSizeTooBig !Natural !Natural
- | BuildTxCollateralShortFall !Natural !Natural
- | BuildTxNoSuitableCollateral
- | BuildTxCborSimplificationError !CborSimplificationError
- | BuildTxCollapseExtraOutError !TxBodyError
- data GYCoinSelectionStrategy
- balanceTxStep ∷ (HasCallStack, MonadRandom m) ⇒ GYBuildTxEnv → Maybe (GYValue, [(GYMintScript v, GYRedeemer)]) → [GYTxInDetailed v] → [GYTxOut v] → GYCoinSelectionStrategy → Natural → m (Either BalancingError ([GYTxInDetailed v], GYUTxOs, [GYTxOut v]))
- finalizeGYBalancedTx ∷ GYBuildTxEnv → GYBalancedTx v → Int → Either BuildTxException GYTxBody
- data BalancingError
- data GYTxInDetailed v = GYTxInDetailed {
- gyTxInDet ∷ !(GYTxIn v)
- gyTxInDetAddress ∷ !GYAddress
- gyTxInDetValue ∷ !GYValue
- gyTxInDetDatum ∷ !GYOutDatum
- gyTxInDetScriptRef ∷ !(Maybe (Some GYScript))
Top level build interface
data GYBuildTxEnv #
A container for various network parameters, and user wallet information, used by balancer.
Constructors
GYBuildTxEnv | |
Fields
|
Arguments
∷ ∀ m v. (HasCallStack, MonadRandom m) | |
⇒ GYBuildTxEnv | |
→ GYCoinSelectionStrategy | |
→ [GYTxInDetailed v] | |
→ [GYTxOut v] | |
→ GYUTxOs | 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 #
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. |
BuildTxSizeTooBig | Transaction size is higher than the maximum as specified by protocol params. |
BuildTxCollateralShortFall | Shortfall (in collateral inputs) for collateral requirement. |
BuildTxNoSuitableCollateral | Couldn't find a UTxO to use as collateral. |
BuildTxCborSimplificationError !CborSimplificationError | |
BuildTxCollapseExtraOutError !TxBodyError |
Instances
IsGYApiError BuildTxException # | |
Defined in GeniusYield.Transaction Methods | |
Exception BuildTxException # | |
Defined in GeniusYield.Transaction | |
Show BuildTxException # | |
Defined in GeniusYield.Transaction |
data GYCoinSelectionStrategy #
Instances
Balancing only
Arguments
∷ (HasCallStack, MonadRandom m) | |
⇒ GYBuildTxEnv | |
→ Maybe (GYValue, [(GYMintScript v, 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.
data BalancingError #
Constructors
BalancingErrorInsufficientFunds !GYValue | |
∀ v. BalancingErrorNonPositiveTxOut !(GYTxOut v) | |
BalancingErrorChangeShortFall !Natural | Lovelace shortfall in constructing a change output. See: Cardano.CoinSelection.Balance.UnableToConstructChangeError |
BalancingErrorEmptyOwnUTxOs | User wallet has no utxos to select. |
Instances
Show BalancingError # | |
Defined in GeniusYield.Transaction.Common | |
Eq BalancingError # | |
Defined in GeniusYield.Transaction.Common Methods (==) ∷ BalancingError → BalancingError → Bool Source # (/=) ∷ BalancingError → BalancingError → Bool Source # |
Utility type
data GYTxInDetailed v #
A further detailed version of GYTxIn
, containing all information about a UTxO.
Constructors
GYTxInDetailed | |
Fields
|
Instances
Show (GYTxInDetailed v) # | |
Defined in GeniusYield.Transaction.Common | |
Eq (GYTxInDetailed v) # | |
Defined in GeniusYield.Transaction.Common Methods (==) ∷ GYTxInDetailed v → GYTxInDetailed v → Bool Source # (/=) ∷ GYTxInDetailed v → GYTxInDetailed v → Bool Source # |