| Copyright | © 2022 IOHK |
|---|---|
| License | Apache-2.0 |
| Safe Haskell | None |
| Language | Haskell2010 |
Cardano.Wallet.CoinSelection
Description
This module provides a wallet-specific interface for coin selection.
Coin selection handles the following responsibilities:
- selecting inputs from the UTxO set to pay for user-specified outputs;
- selecting inputs from the UTxO set to pay for collateral;
- producing change outputs to return excess value to the wallet;
- balancing a selection to pay for the transaction fee.
Use the
performSelection
function to perform a coin selection.
Synopsis
- data WalletSelectionContext
- data WalletUTxO = WalletUTxO { }
- toExternalUTxO :: ( WalletUTxO , TokenBundle ) -> ( TxIn , TxOut )
- toExternalUTxOMap :: Map WalletUTxO TokenBundle -> UTxO
- toInternalUTxO :: ( TxIn , TxOut ) -> ( WalletUTxO , TokenBundle )
- toInternalUTxOMap :: UTxO -> Map WalletUTxO TokenBundle
- toExternalSelection :: Selection WalletSelectionContext -> Selection
- toInternalSelection :: (change -> TokenBundle ) -> SelectionOf change -> Selection WalletSelectionContext
- performSelection :: forall m. ( HasCallStack , MonadRandom m) => SelectionConstraints -> SelectionParams -> ExceptT ( SelectionError WalletSelectionContext ) m Selection
- type Selection = SelectionOf TokenBundle
- data SelectionCollateralRequirement
-
data
SelectionConstraints
=
SelectionConstraints
{
- assessTokenBundleSize :: TokenBundle -> TokenBundleSizeAssessment
- certificateDepositAmount :: Coin
- computeMinimumAdaQuantity :: Address -> TokenMap -> Coin
- isBelowMinimumAdaQuantity :: Address -> TokenBundle -> Bool
- computeMinimumCost :: SelectionSkeleton -> Coin
- computeSelectionLimit :: [ TxOut ] -> SelectionLimit
- maximumCollateralInputCount :: Int
- minimumCollateralPercentage :: Natural
- maximumLengthChangeAddress :: Address
- data SelectionError ctx
- type SelectionLimit = SelectionLimitOf Int
-
data
SelectionLimitOf
a
- = NoLimit
- | MaximumInputLimit a
-
data
SelectionOf
change =
Selection
{
- inputs :: !( NonEmpty ( TxIn , TxOut ))
- collateral :: ![( TxIn , TxOut )]
- outputs :: ![ TxOut ]
- change :: ![change]
- assetsToMint :: ! TokenMap
- assetsToBurn :: ! TokenMap
- extraCoinSource :: ! Coin
- extraCoinSink :: ! Coin
-
data
SelectionParams
=
SelectionParams
{
- assetsToBurn :: ! TokenMap
- assetsToMint :: ! TokenMap
- extraCoinIn :: ! Coin
- extraCoinOut :: ! Coin
- outputsToCover :: ![ TxOut ]
- rewardWithdrawal :: ! Coin
- certificateDepositsTaken :: ! Natural
- certificateDepositsReturned :: ! Natural
- collateralRequirement :: ! SelectionCollateralRequirement
- utxoAvailableForCollateral :: !( Map WalletUTxO TokenBundle )
- utxoAvailableForInputs :: !( UTxOSelection WalletUTxO )
- selectionStrategy :: SelectionStrategy
- data SelectionStrategy
-
data
SelectionSkeleton
=
SelectionSkeleton
{
- skeletonInputCount :: ! Int
- skeletonOutputs :: ![ TxOut ]
- skeletonChange :: ![ Set AssetId ]
- emptySkeleton :: SelectionSkeleton
- data BalanceInsufficientError = BalanceInsufficientError { }
- data SelectionBalanceError ctx
- data SelectionCollateralError ctx
- data SelectionOutputError ctx
-
data
SelectionOutputCoinInsufficientError
ctx =
SelectionOutputCoinInsufficientError
{
- minimumExpectedCoin :: Coin
- output :: ( Address ctx, TokenBundle )
-
newtype
SelectionOutputSizeExceedsLimitError
ctx =
SelectionOutputSizeExceedsLimitError
{
- outputThatExceedsLimit :: ( Address ctx, TokenBundle )
-
data
SelectionOutputTokenQuantityExceedsLimitError
ctx =
SelectionOutputTokenQuantityExceedsLimitError
{
- address :: !( Address ctx)
- asset :: ! AssetId
- quantity :: ! TokenQuantity
- quantityMaxBound :: ! TokenQuantity
-
data
UnableToConstructChangeError
=
UnableToConstructChangeError
{
- requiredCost :: ! Coin
- shortfall :: ! Coin
- makeSelectionReportDetailed :: Selection -> SelectionReportDetailed
- makeSelectionReportSummarized :: Selection -> SelectionReportSummarized
- data SelectionReportDetailed
- data SelectionReportSummarized
- balanceMissing :: BalanceInsufficientError -> TokenBundle
- selectionDelta :: (change -> Coin ) -> SelectionOf change -> Coin
Selection contexts
data WalletSelectionContext Source #
A selection context for the wallet.
Instances
data WalletUTxO Source #
A type of unique UTxO identifier for the wallet.
Constructors
| WalletUTxO | |
Instances
Mapping between external (wallet) types and internal types
toExternalUTxO :: ( WalletUTxO , TokenBundle ) -> ( TxIn , TxOut ) Source #
toInternalUTxO :: ( TxIn , TxOut ) -> ( WalletUTxO , TokenBundle ) Source #
Mapping between external (wallet) selections and internal selections.
toInternalSelection :: (change -> TokenBundle ) -> SelectionOf change -> Selection WalletSelectionContext Source #
Performing selections
performSelection :: forall m. ( HasCallStack , MonadRandom m) => SelectionConstraints -> SelectionParams -> ExceptT ( SelectionError WalletSelectionContext ) m Selection Source #
Performs a coin selection.
This function has the following responsibilities:
- selecting inputs from the UTxO set to pay for user-specified outputs;
- selecting inputs from the UTxO set to pay for collateral;
- producing change outputs to return excess value to the wallet;
- balancing a selection to pay for the transaction fee.
See
performSelection
for more details.
type Selection = SelectionOf TokenBundle Source #
The default type of selection.
In this type of selection, change values do not have addresses assigned.
data SelectionCollateralRequirement Source #
Indicates the collateral requirement for a selection.
Constructors
| SelectionCollateralRequired |
Indicates that collateral is required. |
| SelectionCollateralNotRequired |
Indicates that collateral is not required. |
Instances
data SelectionConstraints Source #
Specifies all constraints required for coin selection.
Selection constraints:
- are dependent on the current set of protocol parameters.
- are not specific to a given selection.
- place limits on the coin selection algorithm, enabling it to produce selections that are acceptable to the ledger.
Constructors
| SelectionConstraints | |
|
Fields
|
|
Instances
data SelectionError ctx Source #
Indicates that an error occurred while performing a coin selection.
Constructors
| SelectionBalanceErrorOf ( SelectionBalanceError ctx) | |
| SelectionCollateralErrorOf ( SelectionCollateralError ctx) | |
| SelectionOutputErrorOf ( SelectionOutputError ctx) |
Instances
| SelectionContext ctx => Eq ( SelectionError ctx) Source # | |
|
Defined in Cardano.Wallet.CoinSelection.Internal Methods (==) :: SelectionError ctx -> SelectionError ctx -> Bool Source # (/=) :: SelectionError ctx -> SelectionError ctx -> Bool Source # |
|
| SelectionContext ctx => Show ( SelectionError ctx) Source # | |
|
Defined in Cardano.Wallet.CoinSelection.Internal |
|
type SelectionLimit = SelectionLimitOf Int Source #
Specifies a limit to adhere to when performing a selection.
data SelectionLimitOf a Source #
Constructors
| NoLimit |
Indicates that there is no limit. |
| MaximumInputLimit a |
Indicates a maximum limit on the number of inputs to select. |
Instances
data SelectionOf change Source #
Represents a balanced selection.
Constructors
| Selection | |
|
Fields
|
|
Instances
data SelectionParams Source #
Specifies all parameters that are specific to a given selection.
Constructors
| SelectionParams | |
|
Fields
|
|
Instances
data SelectionStrategy Source #
Indicates a choice of selection strategy.
A
SelectionStrategy
determines
how much
of each asset the selection
algorithm will attempt to select from the available UTxO set, relative to
the minimum amount necessary to make the selection balance.
The default
SelectionStrategy
is
SelectionStrategyOptimal
, which when
specified will cause the selection algorithm to attempt to select around
twice
the minimum possible 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.
Specifying
SelectionStrategyMinimal
will cause the selection algorithm to
only select
just enough
of each asset from the available UTxO set to
meet the minimum amount. The selection process will terminate as soon as
the minimum amount of each asset is covered.
The "optimal" strategy is recommended for most situations, as 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. This increases the likelihood that future selections will succeed, and lowers the amortized cost of future transactions.
The "minimal" strategy is recommended only for situations where it is not possible to create a selection with the "optimal" strategy. 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. This increases the likelihood that future selections will not succeed, and increases the amortized cost of future transactions.
Constructors
| SelectionStrategyMinimal | |
| SelectionStrategyOptimal |
Instances
| Bounded SelectionStrategy Source # | |
|
|
|
| Enum SelectionStrategy Source # | |
|
Defined in Cardano.Wallet.CoinSelection.Internal.Balance Methods succ :: SelectionStrategy -> SelectionStrategy Source # pred :: SelectionStrategy -> SelectionStrategy Source # toEnum :: Int -> SelectionStrategy Source # fromEnum :: SelectionStrategy -> Int Source # enumFrom :: SelectionStrategy -> [ SelectionStrategy ] Source # enumFromThen :: SelectionStrategy -> SelectionStrategy -> [ SelectionStrategy ] Source # enumFromTo :: SelectionStrategy -> SelectionStrategy -> [ SelectionStrategy ] Source # enumFromThenTo :: SelectionStrategy -> SelectionStrategy -> SelectionStrategy -> [ SelectionStrategy ] Source # |
|
| Eq SelectionStrategy Source # | |
|
Defined in Cardano.Wallet.CoinSelection.Internal.Balance Methods (==) :: SelectionStrategy -> SelectionStrategy -> Bool Source # (/=) :: SelectionStrategy -> SelectionStrategy -> Bool Source # |
|
| Show SelectionStrategy Source # | |
|
|
|
Selection skeletons
data SelectionSkeleton Source #
A skeleton selection that can be used to estimate the cost of a final selection.
Change outputs are deliberately stripped of their asset quantities, as the fee estimation function must be agnostic to the magnitudes of these quantities.
Increasing or decreasing the quantity of a particular asset in a change output must not change the estimated cost of a selection.
Constructors
| SelectionSkeleton | |
|
Fields
|
|
Instances
emptySkeleton :: SelectionSkeleton Source #
Creates an empty
SelectionSkeleton
.
Selection errors
data BalanceInsufficientError Source #
Indicates that the balance of available UTxO entries is insufficient to cover the balance required.
Constructors
| BalanceInsufficientError | |
|
Fields
|
|
Instances
data SelectionBalanceError ctx Source #
Represents the set of errors that may occur while performing a selection.
Constructors
| BalanceInsufficient BalanceInsufficientError | |
| SelectionLimitReached ( SelectionLimitReachedError ctx) | |
| UnableToConstructChange UnableToConstructChangeError | |
| EmptyUTxO |
Instances
data SelectionCollateralError ctx Source #
Represents an unsuccessful attempt to select collateral.
Instances
data SelectionOutputError ctx Source #
Indicates a problem when preparing outputs for a coin selection.
Constructors
Instances
data SelectionOutputCoinInsufficientError ctx Source #
Constructors
| SelectionOutputCoinInsufficientError | |
|
Fields
|
|
Instances
newtype SelectionOutputSizeExceedsLimitError ctx Source #
Constructors
| SelectionOutputSizeExceedsLimitError | |
|
Fields
|
|
Instances
data SelectionOutputTokenQuantityExceedsLimitError ctx Source #
Indicates that a token quantity exceeds the maximum quantity that can appear in a transaction output's token bundle.
Constructors
| SelectionOutputTokenQuantityExceedsLimitError | |
|
Fields
|
|
Instances
data UnableToConstructChangeError Source #
Constructors
| UnableToConstructChangeError | |
|
Fields
|
|
Instances
Selection reports
data SelectionReportDetailed Source #
Includes detailed information about a selection.
Instances
data SelectionReportSummarized Source #
Includes summarized information about a selection.
Each data point can be serialized as a single line of text.
Instances
Selection deltas
balanceMissing :: BalanceInsufficientError -> TokenBundle Source #
Calculate the missing balance from a
BalanceInsufficientError
.
Arguments
| :: (change -> Coin ) |
A function to extract the coin value from a change value. |
| -> SelectionOf change | |
| -> Coin |
Computes the ada surplus of a selection, assuming there is a surplus.