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)]) → [GYTxWdrl v] → [GYTxCert v] → Maybe GYSlot → Maybe GYSlot → Set GYPubKeyHash → Maybe GYTxMetadata → m (Either GYBuildTxError GYTxBody)
- data GYBuildTxError
- = GYBuildTxBalancingError !GYBalancingError
- | GYBuildTxBodyErrorAutoBalance !(TxBodyErrorAutoBalance ApiEra)
- | GYBuildTxExUnitsTooBig (Natural, Natural) (Natural, Natural)
- | GYBuildTxSizeTooBig !Natural !Natural
- | GYBuildTxCollateralShortFall !Natural !Natural
- | GYBuildTxNoSuitableCollateral
- | GYBuildTxCborSimplificationError !CborSimplificationError
- | GYBuildTxCollapseExtraOutError !TxBodyError
- data GYCoinSelectionStrategy
- balanceTxStep ∷ (HasCallStack, MonadRandom m) ⇒ GYBuildTxEnv → Maybe (GYValue, [(GYMintScript v, GYRedeemer)]) → [GYTxWdrl v] → [GYTxCert' v] → [GYTxInDetailed v] → [GYTxOut v] → GYCoinSelectionStrategy → Natural → m (Either GYBalancingError ([GYTxInDetailed v], GYUTxOs, [GYTxOut v]))
- finalizeGYBalancedTx ∷ GYBuildTxEnv → GYBalancedTx v → Int → Either GYBuildTxError GYTxBody
- data GYBalancingError
- 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, [(GYMintScript v, GYRedeemer)]) | minted values |
→ [GYTxWdrl v] | withdrawals |
→ [GYTxCert v] | certificates |
→ Maybe GYSlot | |
→ Maybe GYSlot | |
→ Set GYPubKeyHash | |
→ Maybe GYTxMetadata | |
→ m (Either GYBuildTxError GYTxBody) |
Pure interface to build the transaction body given necessary information.
data GYBuildTxError #
GYBuildTxError
may be raised when building transactions, for non-trivial errors.
Insufficient funds and similar are considered trivial transaction building errors.
Constructors
GYBuildTxBalancingError !GYBalancingError | |
GYBuildTxBodyErrorAutoBalance !(TxBodyErrorAutoBalance ApiEra) | |
GYBuildTxExUnitsTooBig | Execution units required is higher than the maximum as specified by protocol params. |
GYBuildTxSizeTooBig | Transaction size is higher than the maximum as specified by protocol params. |
GYBuildTxCollateralShortFall | Shortfall (in collateral inputs) for collateral requirement. |
GYBuildTxNoSuitableCollateral | Couldn't find a UTxO to use as collateral. |
GYBuildTxCborSimplificationError !CborSimplificationError | |
GYBuildTxCollapseExtraOutError !TxBodyError |
Instances
Show GYBuildTxError # | |
Defined in GeniusYield.Transaction.Common Methods showsPrec ∷ Int → GYBuildTxError → ShowS # show ∷ GYBuildTxError → String # showList ∷ [GYBuildTxError] → ShowS # |
data GYCoinSelectionStrategy #
Instances
Balancing only
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 GYBalancingError ([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 GYBalancingError #
Constructors
GYBalancingErrorInsufficientFunds !GYValue | |
∀ v. GYBalancingErrorNonPositiveTxOut !(GYTxOut v) | |
GYBalancingErrorChangeShortFall !Natural | Lovelace shortfall in constructing a change output. See: Cardano.CoinSelection.Balance.UnableToConstructChangeError |
GYBalancingErrorEmptyOwnUTxOs | User wallet has no utxos to select. |
Instances
Show GYBalancingError # | |
Defined in GeniusYield.Transaction.Common Methods showsPrec ∷ Int → GYBalancingError → ShowS # show ∷ GYBalancingError → String # showList ∷ [GYBalancingError] → ShowS # | |
PrintfArg GYBalancingError # | |
Defined in GeniusYield.Transaction.Common Methods | |
Eq GYBalancingError # | |
Defined in GeniusYield.Transaction.Common Methods |
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 Methods showsPrec ∷ Int → GYTxInDetailed v → ShowS # show ∷ GYTxInDetailed v → String # showList ∷ [GYTxInDetailed v] → ShowS # | |
Eq (GYTxInDetailed v) # | |
Defined in GeniusYield.Transaction.Common Methods (==) ∷ GYTxInDetailed v → GYTxInDetailed v → Bool # (/=) ∷ GYTxInDetailed v → GYTxInDetailed v → Bool # |