Documentation

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.

Specifies all constraints required for coin selection.

Specifies all parameters that are specific to a given selection.

The result of performing a successful selection.

Represents the set of errors that may occur while performing a selection.

Indicates that the balance of available UTxO entries is insufficient to cover the balance required.

See computeUTxOBalanceSufficiency.

Performs a coin selection and generates change values in one step.

Provided that isUTxOBalanceSufficient returns True for the given selection criteria, this function guarantees to return a SelectionResult for which selectionHasValidSurplus returns True.

Indicates whether or not a selection result has a valid surplus.

Calculates the ada selection delta.

See SelectionDelta.

Calculates the ada selection surplus, assuming there is a surplus.

If there is a surplus, then this function returns that surplus. If there is a deficit, then this function returns zero.

Use selectionDeltaCoin if you wish to handle the case where there is a deficit.