Coin selection

This module contains algorithms that select UTxOs from a parent list to satisfy some output constraints.

class pycardano.coinselection.UTxOSelector

Bases: object

UTxOSelector defines an interface through which a subset of UTxOs should be selected from a parent set with a selection strategy and given constraints.

select(utxos: List[UTxO], outputs: List[TransactionOutput], context: ChainContext, max_input_count: Optional[int] = None, include_max_fee: Optional[bool] = True, respect_min_utxo: Optional[bool] = True) → Tuple[List[UTxO], Value]

From an input list of UTxOs, select a subset of UTxOs whose sum (including ADA and multi-assets) is equal to or larger than the sum of a set of outputs.

Parameters:

  • utxos (List[UTxO]) – A list of UTxO to select from.

  • outputs (List[TransactionOutput]) – A list of transaction outputs which the selected set should satisfy.

  • context (ChainContext) – A chain context where protocol parameters could be retrieved.

  • max_input_count (int) – Max number of input UTxOs to select.

  • include_max_fee (bool) – Have selected UTxOs to cover transaction fee. Defaults to True. If disabled, there is a possibility that selected UTxO are not able to cover the fee of the transaction.

  • respect_min_utxo (bool) – Respect minimum amount of ADA required to hold a multi-asset bundle in the change. Defaults to True. If disabled, the selection will not add addition amount of ADA to change even when the amount is too small to hold a multi-asset bundle.

Returns:

A tuple containing:

selected (List[UTxO]): A list of selected UTxOs.

changes (Value): Change amount to be returned.

Return type:

Tuple[List[UTxO], Value]

Raises:
class pycardano.coinselection.LargestFirstSelector

Bases: UTxOSelector

Largest first selection algorithm as specified in https://github.com/cardano-foundation/CIPs/tree/master/CIP-0002#largest-first.

This implementation adds transaction fee into consideration.

select(utxos: List[UTxO], outputs: List[TransactionOutput], context: ChainContext, max_input_count: Optional[int] = None, include_max_fee: Optional[bool] = True, respect_min_utxo: Optional[bool] = True) → Tuple[List[UTxO], Value]

From an input list of UTxOs, select a subset of UTxOs whose sum (including ADA and multi-assets) is equal to or larger than the sum of a set of outputs.

Parameters:

  • utxos (List[UTxO]) – A list of UTxO to select from.

  • outputs (List[TransactionOutput]) – A list of transaction outputs which the selected set should satisfy.

  • context (ChainContext) – A chain context where protocol parameters could be retrieved.

  • max_input_count (int) – Max number of input UTxOs to select.

  • include_max_fee (bool) – Have selected UTxOs to cover transaction fee. Defaults to True. If disabled, there is a possibility that selected UTxO are not able to cover the fee of the transaction.

  • respect_min_utxo (bool) – Respect minimum amount of ADA required to hold a multi-asset bundle in the change. Defaults to True. If disabled, the selection will not add addition amount of ADA to change even when the amount is too small to hold a multi-asset bundle.

Returns:

A tuple containing:

selected (List[UTxO]): A list of selected UTxOs.

changes (Value): Change amount to be returned.

Return type:

Tuple[List[UTxO], Value]

Raises:
class pycardano.coinselection.RandomImproveMultiAsset(random_generator: Optional[Iterable[int]] = None)

Bases: UTxOSelector

Random-improve selection algorithm as specified in https://github.com/cardano-foundation/CIPs/tree/master/CIP-0002#random-improve.

Because the original algorithm does not take multi-assets into consideration, this implementation is slightly different from the algorithm. The main modification is that it merges all requested transaction outputs into one, including all native assets, and then treat each merged native asset as an individual transaction output request.

This idea is inspired by Nami wallet: https://github.com/Berry-Pool/nami-wallet/blob/main/src/lib/coinSelection.js

Note

Although this implementation is similar to the original Random-improve algorithm, and it is being used by some wallets, there are no substantial evidences or proofs showing that this implementation will still be able to correctly optimize UTxO selection based on three heuristics mentioned in the doc.

select(utxos: List[UTxO], outputs: List[TransactionOutput], context: ChainContext, max_input_count: Optional[int] = None, include_max_fee: Optional[bool] = True, respect_min_utxo: Optional[bool] = True) → Tuple[List[UTxO], Value]

From an input list of UTxOs, select a subset of UTxOs whose sum (including ADA and multi-assets) is equal to or larger than the sum of a set of outputs.

Parameters:

  • utxos (List[UTxO]) – A list of UTxO to select from.

  • outputs (List[TransactionOutput]) – A list of transaction outputs which the selected set should satisfy.

  • context (ChainContext) – A chain context where protocol parameters could be retrieved.

  • max_input_count (int) – Max number of input UTxOs to select.

  • include_max_fee (bool) – Have selected UTxOs to cover transaction fee. Defaults to True. If disabled, there is a possibility that selected UTxO are not able to cover the fee of the transaction.

  • respect_min_utxo (bool) – Respect minimum amount of ADA required to hold a multi-asset bundle in the change. Defaults to True. If disabled, the selection will not add addition amount of ADA to change even when the amount is too small to hold a multi-asset bundle.

Returns:

A tuple containing:

selected (List[UTxO]): A list of selected UTxOs.

changes (Value): Change amount to be returned.

Return type:

Tuple[List[UTxO], Value]

Raises: