Ctl.Internal.BalanceTx.CoinSelection

newtype SelectionState

Represents the internal state of a selection.

Taken from cardano-wallet: https://github.com/input-output-hk/cardano-wallet/blob/a61d37f2557b8cb5c47b57da79375afad698eed4/lib/wallet/src/Cardano/Wallet/Primitive/Types/UTxOSelection.hs#L145

Constructors

• SelectionState { leftoverUtxos :: UtxoIndex, selectedUtxos :: UtxoMap }

Instances

• Generic SelectionState _
• Newtype SelectionState _
• Eq SelectionState
• Show SelectionState

data SelectionStrategy

A SelectionStrategy determines how much of each asset the selection algorithm will attempt to select from the available utxo set.

Specifying SelectionStrategyOptimal will cause the selection algorithm to attempt to select around twice the required amount of each asset from the available utxo set, making it possible to generate change outputs that are roughly the same sizes and shapes as the user-specified outputs. Using this strategy will help to ensure that a wallet's utxo distribution can evolve over time to resemble the typical distribution of payments made by the wallet owner.

Specifying SelectionStrategyMinimal will cause the selection algorithm to only select just enough of each asset from the available utxo set to meet the required amount. It is advised to use this strategy only when necessary, as it increases the likelihood of generating change outputs that are much smaller than user-specified outputs. If this strategy is used regularly, the utxo set can evolve to a state where the distribution no longer resembles the typical distribution of payments made by the user.

Taken from cardano-wallet: https://github.com/input-output-hk/cardano-wallet/blob/a61d37f2557b8cb5c47b57da79375afad698eed4/lib/wallet/src/Cardano/Wallet/CoinSelection/Internal/Balance.hs#L325

Constructors

• SelectionStrategyOptimal
• SelectionStrategyMinimal

Instances

• Arbitrary SelectionStrategy

_leftoverUtxos :: Lens' SelectionState UtxoIndex

empty :: SelectionState

A completely empty selection with no selected or leftover UTxOs.

Taken from cardano-wallet: https://github.com/input-output-hk/cardano-wallet/blob/9d73b57e23392e25148cfc8db560cb8f656cb56a/lib/primitive/lib/Cardano/Wallet/Primitive/Types/UTxOSelection.hs#L183

fromIndexFiltered :: (TransactionInput -> Boolean) -> UtxoIndex -> SelectionState

mkSelectionState :: UtxoIndex -> SelectionState

Creates an initial SelectionState where none of the utxos are selected.

Taken from cardano-wallet: https://github.com/input-output-hk/cardano-wallet/blob/a61d37f2557b8cb5c47b57da79375afad698eed4/lib/wallet/src/Cardano/Wallet/Primitive/Types/UTxOSelection.hs#L192

performMultiAssetSelection :: forall (m :: Type -> Type). MonadEffect m => MonadThrow BalanceTxError m => SelectionStrategy -> UtxoIndex -> Val -> m SelectionState

Performs a coin selection using the specified selection strategy.

Throws a BalanceInsufficientError if the balance of the provided utxo set is insufficient to cover the balance required.

Taken from cardano-wallet: https://github.com/input-output-hk/cardano-wallet/blob/a61d37f2557b8cb5c47b57da79375afad698eed4/lib/wallet/src/Cardano/Wallet/CoinSelection/Internal/Balance.hs#L1128

runRoundRobinM :: forall (m :: Type -> Type) (s :: Type). Monad m => s -> Array (Processor m s) -> m s

Uses given processors to update the state sequentially. Removes the processor from the list if applying it to the state returns Nothing. Each processor can only be applied once per round and is carried over to the next round if it has successfully updated the state.

We use Round-robin processing to perform coin selection in multiple rounds, where a Processor runs a single selection step (runSelectionStep) for an asset from the set of all assets present in requiredValue. It returns Nothing in case the selection for a particular asset is already optimal and cannot be improved further.

Taken from cardano-wallet: https://github.com/input-output-hk/cardano-wallet/blob/3395b6e4749544d552125dfd0e060437b5c18d5c/lib/coin-selection/lib/Cardano/CoinSelection/Balance.hs#L2155

selectedInputs :: SelectionState -> Set TransactionInput

Returns the output references of the selected utxos.

selectUtxo :: TxUnspentOutput -> SelectionState -> SelectionState

Moves a single utxo entry from the leftover set to the selected set.

Taken from cardano-wallet: https://github.com/input-output-hk/cardano-wallet/blob/a61d37f2557b8cb5c47b57da79375afad698eed4/lib/wallet/src/Cardano/Wallet/Primitive/Types/UTxOSelection.hs#L426

selectRandomWithPriority :: forall (m :: Type -> Type). MonadEffect m => UtxoIndex -> NonEmptyArray SelectionFilter -> m (Maybe (TxUnspentOutput /\ UtxoIndex))

Taken from cardano-wallet: https://github.com/input-output-hk/cardano-wallet/blob/3d722b27f6dbd2cf05da497297e60e3b54b1ef6e/lib/wallet/src/Cardano/Wallet/Primitive/Types/UTxOIndex/Internal.hs#L460