Performs a coin selection and generates change bundles 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 .

Transforms a coin selection function that requires a non-empty list of outputs into a function that accepts an empty list of outputs.

If the original list is already non-empty, this function does not alter the parameters or the result in any way, such that:

params == transformParams params result == transformResult result

If the original list is empty, this function:

1. applies a balance-preserving transformation to the parameters, adding a single minimal ada-only output to act as a change generation target, such that:

   computeUTxOBalanceSufficiencyInfo params == computeUTxOBalanceSufficiencyInfo (transformParams params)

2. applies an inverse transformation to the result, removing the output, such that:

   selectionSurplus result == selectionSurplus (transformResult result)

   selectionHasValidSurplus constraints result ==> selectionHasValidSurplus constraints (transformResult result)

Specifies all constraints required for coin selection.

Selection constraints:

• place limits on the coin selection algorithm, enabling it to produce selections that are acceptable to the ledger.
• are dependent on the current set of protocol parameters.
• are not specific to a given selection.

Specifies all parameters that are specific to a given selection.

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.

The result of performing a successful selection.

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.

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 .

Specifies a limit to adhere to when performing a selection.

Indicates whether or not the given selection limit has been exceeded.

Indicates that the balance of selected UTxO entries was insufficient to cover the balance required while remaining within the selection limit.

Reduces a selection limit by a given reduction amount.

If the given reduction amount is positive, then this function will reduce the selection limit by that amount.

If the given reduction amount is zero or negative, then this function will return the original limit unchanged.

Indicates the difference between total input value and total output value of a SelectionResult .

There are two possibilities:

• SelectionSurplus

Indicates a surplus, when the total input value is greater than or equal to the total output value.

• SelectionDeficit

Indicates a deficit, when the total input value is NOT greater than or equal to the total output value.

Calculates the selection delta for all assets.

See SelectionDelta .

Calculates the ada selection delta.

See SelectionDelta .

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

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.

Computes the minimum required cost of a selection.

Computes the maximum acceptable cost of a selection.

This function acts as a safety limit to ensure that fees of selections produced by performSelection are not excessively high.

Ideally, we'd always be able to generate selections with fees that are precisely equal to selectionMinimumCost . However, in some situations it may be necessary to exceed this cost very slightly.

This function provides a conservative upper bound to a selection cost that we can reference from within property tests.

See selectionHasValidSurplus .

Converts a selection into a skeleton.

Indicates whether the balance of available UTxO entries is sufficient.

See computeUTxOBalanceSufficiency .

Gives more information about UTxO balance sufficiency.

See computeUTxOBalanceSufficiencyInfo .

Computes the balance of UTxO entries available for selection.

Computes the balance of UTxO entries required to be selected.

Computes the UTxO balance sufficiency.

See UTxOBalanceSufficiency .

Computes information about the UTxO balance sufficiency.

See UTxOBalanceSufficiencyInfo .

Indicates whether or not the UTxO balance is sufficient.

The balance of available UTxO entries is sufficient if (and only if) it is greater than or equal to the required balance.

Parameters for runSelection .

Runs just a single step of a coin selection.

It returns an updated state if (and only if) the updated selection represents an improvement over the selection in the previous state.

An improvement, for a given token quantity, is defined in the following way:

• If the total selected token quantity of the previous selection had not yet reached 100% of the output token quantity, any additional selection is considered to be an improvement.
• If the total selected token quantity of the previous selection had already reached or surpassed 100% of the output token quantity, any additional selection is considered to be an improvement if and only if it takens the total selected token quantity closer to the target token quantity, but not further away.

Provides a lens on the current selection state.

A SelectionLens gives runSelectionStep just the information it needs to make a decision, and no more.

Criteria for the makeChange function.

Constructs change bundles for a set of selected inputs and outputs.

Returns Nothing if the specified inputs do not provide enough ada to satisfy the minimum delta and minimum ada quantities of the change bundles generated.

This function will generate runtime errors if:

1. The total balance of all outputs is not less than or equal to the total balance of all inputs.
2. The total ada balance of all outputs is zero.

Pre-condition (1) should be satisfied by any result produced by the runSelection function.

Pre-condition (2) should be satisfied by assigning a minimum ada quantity to every output token bundle.

Constructs a list of ada change outputs based on the given distribution.

If the sum of weights in given distribution is equal to zero, this function throws a runtime error.

The length of the output list is always the same as the length of the input list, and the sum of its quantities is always exactly equal to the Coin value given as the second argument.

Constructs change outputs for a user-specified asset: an asset that was present in the original set of outputs.

If the given asset does not appear in the given distribution, this function returns a list of empty token maps. Otherwise, the given token quantity is partitioned into a list of quantities that are proportional to the weights within the given input distribution, modulo rounding.

The length of the output list is always the same as the the length of the input list, and the sum of its quantities is either zero, or exactly equal to the token quantity in the second argument.

Constructs change outputs for a non-user-specified asset: an asset that was not present in the original set of outputs.

This function constructs a list of change outputs by preserving the input distribution as much as possible. Note that only the length of the first argument is used.

The length of the output list is always the same as the length of the input list, and the sum of its quantities is always exactly equal to the sum of all token quantities given in the second argument.

The resultant list is sorted into ascending order when maps are compared with the leq function.

Constructs change outputs for all non-user-specified assets: assets that were not present in the original set of outputs.

The resultant list is sorted into ascending order when maps are compared with the leq function.

Assigns coin quantities to a list of pre-computed asset change maps.

Each pre-computed asset change map must be paired with the original coin value of its corresponding output.

This function:

• expects the list of pre-computed asset change maps to be sorted in an order that ensures all empty token maps are at the start of the list.
• attempts to assign a minimum ada quantity to every change map, but iteratively drops empty change maps from the start of the list if the amount of ada is insufficient to cover them all.
• continues dropping empty change maps from the start of the list until it is possible to assign a minimum ada value to all remaining entries.
• returns a list that is identical in length to the input list if (and only if) it was possible to assign a minimum ada quantity to all change maps.
• returns a list that is shorter than the input list if it was only possible to assign a minimum ada quantity to a suffix of the given list.
• fails if (and only if) there was not enough ada available to assign the minimum ada quantity to all non-empty change maps.

Generates a map of all non-user-specified assets and their quantities.

Each key in the resulting map corresponds to an asset that was NOT included in the original set of user-specified outputs, but that was nevertheless selected during the selection process.

The value associated with each key corresponds to the complete list of all discrete non-zero quantities of that asset present in the selected inputs.

Adds a minted asset quantity to a list of change maps.

This function always adds the given quantity to the final change map in the given list.

Example:

Suppose we have the following list of change maps:

[ ( B , 7)

[( A , 1), ( B , 8)

[( A , 2), ( B , 9)

[( A , 3), ( B , 9)

[( A , 4), ( B , 12)

If we add 4 tokens of asset A , we obtain the following result:

[ ( B , 7)

[( A , 1), ( B , 8)

[( A , 2), ( B , 9)

[( A , 3), ( B , 9)

[( A , 8), ( B , 12)

-- Increased by 4

Provided that the specified change maps are in ascending partial order, this function guarantees that the resulting change maps will also be in ascending partial order.

The length of the given list is preserved in the output list.

Adds minted values for multiple assets to a list of change maps.

Plural of addMintValueToChangeMaps .

Removes a burned asset quantity from a list of change maps.

For a given asset a and reduction target t , this function traverses the given list from left to right, reducing the quantity of asset a in each change map until the reduction target t has been met, or until the list is exhausted.

For each change map m under consideration:

• if the quantity q of asset a in map m is less than or equal to the remaining required reduction r , it will be replaced with a zero (effectively eliminating asset a from the map).
• if the quantity q of asset a in map m is greater than the remaining required reduction r , it will be replaced with the absolute difference between q and r .

If the total quantity of the given asset in the given change maps is greater than the specified reduction target, the total reduction will be equal to the specified reduction target. Otherwise, the given asset will be completely eliminated from all change maps.

Example:

Suppose we have the following list of change maps:

[ ( B , 7)

[( A , 1), ( B , 8)

[( A , 2), ( B , 9)

[( A , 3), ( B , 9)

[( A , 4), ( B , 12)

If our target is to reduce the quantity of asset A by 4, then we should obtain the following result:

[ ( B , 7)

-- Unable to reduce (already 0)

[ ( B , 8)

-- Reduced by 1 (and eliminated from map)

[ ( B , 9)

-- Reduced by 2 (and eliminated from map)

[( A , 2), ( B , 9)

-- Reduced by 1

[( A , 4), ( B , 12)

Provided that the specified change maps are in ascending partial order, this function guarantees that the resulting change maps will also be in ascending partial order.

The length of the given list is preserved in the output list.

Removes burned values for multiple assets from a list of change maps.

Plural of removeBurnValueFromChangeMaps .

Reduces the total value of the given list of token quantities by the given reduction target.

This function traverses the given list of quantities from left to right, reducing each quantity in turn until the total reduction is equal to the given reduction target, or until the list is exhausted.

For each quantity q under consideration:

• if q is less than or equal to the remaining required reduction r , it will be replaced with a zero.
• if q is greater than the remaining required reduction r , it will be replaced with the absolute difference between q and r .

If the total value in the list is less than the reduction target, the result will be a list of zeros.

Provided the given list is in ascending order, the resulting list is also guaranteed to be in ascending order.

The length of the given list is preserved in the output.

Splits a bundle into smaller bundles if its asset count is excessive when measured with the given isExcessive indicator function.

Returns a list of smaller bundles for which isExcessive returns False .

Splits bundles with excessive asset counts into smaller bundles.

Only token bundles where the isExcessive indicator function returns True will be split.

Returns a list of smaller bundles for which isExcessive returns False .

If none of the bundles in the given list has an excessive asset count, this function will return the original list.

Splits bundles with excessive token quantities into smaller bundles.

Only token bundles containing quantities that exceed the maximum token quantity will be split.

If none of the bundles in the given list contain a quantity that exceeds the maximum token quantity, this function will return the original list.

Calculate the missing balance from a BalanceInsufficientError .