Copyright | (c) 2023 GYELD GMBH |
---|---|
License | Apache 2.0 |
Maintainer | [email protected] |
Stability | develop |
Safe Haskell | None |
Language | Haskell2010 |
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 - TODO: Improve wording here after complete setup of not requiring reserved collateral.
- 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? #22 | https://github.com/geniusyield/atlas/issues/22)
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 {
- gyBTxEnvSystemStart ∷ !SystemStart
- gyBTxEnvEraHistory ∷ !(EraHistory CardanoMode)
- gyBTxEnvProtocolParams ∷ !ProtocolParameters
- gyBTxEnvPools ∷ !(Set PoolId)
- gyBTxEnvOwnUtxos ∷ !GYUTxOs
- gyBTxEnvChangeAddr ∷ !GYAddress
- gyBTxEnvCollateral ∷ !GYUTxO
- buildUnsignedTxBody ∷ ∀ m v. (HasCallStack, MonadRandom m) ⇒ GYBuildTxEnv → GYCoinSelectionStrategy → [GYTxInDetailed v] → [GYTxOut v] → GYUTxOs → Maybe (GYValue, [(Some GYMintingPolicy, GYRedeemer)]) → Maybe GYSlot → Maybe GYSlot → Set GYPubKeyHash → m (Either BuildTxException GYTxBody)
- data BuildTxException
- data GYCoinSelectionStrategy
- balanceTxStep ∷ (HasCallStack, MonadRandom m) ⇒ GYBuildTxEnv → Bool → Maybe (GYValue, [(Some GYMintingPolicy, GYRedeemer)]) → [GYTxInDetailed v] → [GYTxOut v] → GYCoinSelectionStrategy → Natural → m (Either BalancingError ([GYTxInDetailed v], GYUTxOs, [GYTxOut v]))
- finalizeGYBalancedTx ∷ GYBuildTxEnv → Bool → GYBalancedTx v → Either BuildTxException GYTxBody
- data BalancingError
- data GYTxInDetailed v = GYTxInDetailed {}
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, [(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. |
BuildTxCollateralShortFall !Natural | Lovelaces shortfall (in collateral inputs) for collateral requirement. |
BuildTxNoSuitableCollateral | Couldn't find a UTxO to use as collateral. |
Instances
Show BuildTxException # | |
Defined in GeniusYield.Transaction Methods showsPrec ∷ Int → BuildTxException → ShowS # show ∷ BuildTxException → String # showList ∷ [BuildTxException] → ShowS # | |
Exception BuildTxException # | |
Defined in GeniusYield.Transaction | |
IsGYApiError BuildTxException # | |
Defined in GeniusYield.Transaction Methods |
data GYCoinSelectionStrategy #
Instances
Eq GYCoinSelectionStrategy # | |
Defined in GeniusYield.Transaction.CoinSelection | |
Show GYCoinSelectionStrategy # | |
Defined in GeniusYield.Transaction.CoinSelection |
Balancing only
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.
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
Eq BalancingError # | |
Defined in GeniusYield.Transaction.Common Methods (==) ∷ BalancingError → BalancingError → Bool # (/=) ∷ BalancingError → BalancingError → Bool # | |
Show BalancingError # | |
Defined in GeniusYield.Transaction.Common Methods showsPrec ∷ Int → BalancingError → ShowS # show ∷ BalancingError → String # showList ∷ [BalancingError] → ShowS # |
Utility type
data GYTxInDetailed v #
A further detailed version of GYTxIn
, containing all information about a UTxO.
Constructors
GYTxInDetailed | |
Fields
|
Instances
Eq (GYTxInDetailed v) # | |
Defined in GeniusYield.Transaction.Common Methods (==) ∷ GYTxInDetailed v → GYTxInDetailed v → Bool # (/=) ∷ GYTxInDetailed v → GYTxInDetailed v → Bool # | |
Show (GYTxInDetailed v) # | |
Defined in GeniusYield.Transaction.Common Methods showsPrec ∷ Int → GYTxInDetailed v → ShowS # show ∷ GYTxInDetailed v → String # showList ∷ [GYTxInDetailed v] → ShowS # |