Copyright	© 2018-2020 IOHK
License	Apache-2.0
Safe Haskell	None
Language	Haskell2010

Cardano.CoinSelection

Contents

Coin Selections
Coin Selection Algorithms
Coins
Coin Maps
Coin Selection Errors

Description

Provides general functions and types relating to coin selection.

The CoinSelection type represents a coin selection, the basis for a transaction in a UTxO-based blockchain.

The CoinSelectionAlgorithm type provides a common interface to algorithms that generate coin selections.

For a guide to algorithms provided by this library, see the Cardano.CoinSelection.Algorithm module.

To adjust coin selections in order to pay for transaction fees, see the Cardano.CoinSelection.Fee module.

Synopsis

data CoinSelection i o = CoinSelection {
- inputs :: CoinMap i
- outputs :: CoinMap o
- change :: [Coin]
}
sumInputs :: CoinSelection i o -> Coin
sumOutputs :: CoinSelection i o -> Coin
sumChange :: CoinSelection i o -> Coin
newtype CoinSelectionAlgorithm i o m = CoinSelectionAlgorithm {
- selectCoins :: CoinSelectionParameters i o -> ExceptT CoinSelectionError m (CoinSelectionResult i o)
}
data CoinSelectionParameters i o = CoinSelectionParameters {
- inputsAvailable :: CoinMap i
- outputsRequested :: CoinMap o
- limit :: CoinSelectionLimit
}
data CoinSelectionResult i o = CoinSelectionResult {
- coinSelection :: CoinSelection i o
- inputsRemaining :: CoinMap i
}
newtype CoinSelectionLimit = CoinSelectionLimit {
- calculateLimit :: Word16 -> Word16
}
data Coin
coinFromNatural :: Natural -> Coin
coinToNatural :: Coin -> Natural
newtype CoinMap a = CoinMap {
- unCoinMap :: Map a Coin
}
data CoinMapEntry a = CoinMapEntry {
- entryKey :: a
- entryValue :: Coin
}
coinMapFromList :: Ord a => [CoinMapEntry a] -> CoinMap a
coinMapToList :: CoinMap a -> [CoinMapEntry a]
coinMapValue :: CoinMap a -> Coin
data CoinSelectionError
- = InputValueInsufficient InputValueInsufficientError
- | InputCountInsufficient InputCountInsufficientError
- | InputLimitExceeded InputLimitExceededError
- | InputsExhausted InputsExhaustedError
data InputValueInsufficientError = InputValueInsufficientError {
- inputValueAvailable :: Coin
- inputValueRequired :: Coin
}
data InputCountInsufficientError = InputCountInsufficientError {
- inputCountAvailable :: Natural
- inputCountRequired :: Natural
}
newtype InputLimitExceededError = InputLimitExceededError {
- calculatedInputLimit :: Word16
}
data InputsExhaustedError = InputsExhaustedError

Coin Selections

data CoinSelection i o Source #

A coin selection is the basis for a transaction.

It consists of a selection of inputs, outputs, and change.

The inputs and outputs fields are both maps of unique keys to associated Coin values, where:

Each key-value pair in the inputs map corresponds to an unspent output from a previous transaction (also known as a UTxO). The key is a unique reference to that output, and the value is the amount of unspent value associated with it.
Each key-value pair in the outputs map corresponds to a payment. The key is a unique reference to a payment recipient, and the value is the amount of money to pay to that recipient.

The change field is a set of coins to be returned to the originator of the transaction.

The CoinSelectionAlgorithm type provides a common interface for generating coin selections.

Since: 1.0.0

Constructors

CoinSelection
Fields inputs :: CoinMap i The set of inputs. outputs :: CoinMap o The set of outputs. change :: [Coin] The set of change.

Instances

(Eq i, Eq o) => Eq (CoinSelection i o) Source #
Instance details Defined in Cardano.CoinSelection Methods (==) :: CoinSelection i o -> CoinSelection i o -> Bool # (/=) :: CoinSelection i o -> CoinSelection i o -> Bool #
(Show i, Show o) => Show (CoinSelection i o) Source #
Instance details Defined in Cardano.CoinSelection Methods showsPrec :: Int -> CoinSelection i o -> ShowS # show :: CoinSelection i o -> String # showList :: [CoinSelection i o] -> ShowS #
Generic (CoinSelection i o) Source #
Instance details Defined in Cardano.CoinSelection Associated Types type Rep (CoinSelection i o) :: Type -> Type # Methods from :: CoinSelection i o -> Rep (CoinSelection i o) x # to :: Rep (CoinSelection i o) x -> CoinSelection i o #
(Ord i, Ord o) => Semigroup (CoinSelection i o) Source #
Instance details Defined in Cardano.CoinSelection Methods (<>) :: CoinSelection i o -> CoinSelection i o -> CoinSelection i o # sconcat :: NonEmpty (CoinSelection i o) -> CoinSelection i o # stimes :: Integral b => b -> CoinSelection i o -> CoinSelection i o #
(Ord i, Ord o) => Monoid (CoinSelection i o) Source #
Instance details Defined in Cardano.CoinSelection Methods mempty :: CoinSelection i o # mappend :: CoinSelection i o -> CoinSelection i o -> CoinSelection i o # mconcat :: [CoinSelection i o] -> CoinSelection i o #
type Rep (CoinSelection i o) Source #
Instance details Defined in Cardano.CoinSelection type Rep (CoinSelection i o) = D1 (MetaData "CoinSelection" "Cardano.CoinSelection" "cardano-coin-selection-1.0.1-ArWDQ7GeNjh2nML9dPNIzs" False) (C1 (MetaCons "CoinSelection" PrefixI True) (S1 (MetaSel (Just "inputs") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (CoinMap i)) :: (S1 (MetaSel (Just "outputs") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (CoinMap o)) :: S1 (MetaSel (Just "change") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Coin]))))

sumInputs :: CoinSelection i o -> Coin Source #

Calculate the total sum of all inputs for the given CoinSelection.

Since: 1.0.0

sumOutputs :: CoinSelection i o -> Coin Source #

Calculate the total sum of all outputs for the given CoinSelection.

Since: 1.0.0

sumChange :: CoinSelection i o -> Coin Source #

Calculate the total sum of all change for the given CoinSelection.

Since: 1.0.0

Coin Selection Algorithms

newtype CoinSelectionAlgorithm i o m Source #

Provides a common interface for coin selection algorithms.

The function selectCoins, when applied to the given CoinSelectionParameters object (with available inputs and requested outputs), will generate a CoinSelectionResult (with remaining inputs and a coin selection).

For implementations provided by this library, see Cardano.CoinSelection.Algorithm.

Since: 1.0.0

Constructors

CoinSelectionAlgorithm
Fields selectCoins :: CoinSelectionParameters i o -> ExceptT CoinSelectionError m (CoinSelectionResult i o)

data CoinSelectionParameters i o Source #

The complete set of parameters required for a CoinSelectionAlgorithm.

The inputsAvailable and outputsRequested fields are both maps of unique keys to associated Coin values, where:

Each key-value pair in the inputsAvailable map corresponds to an unspent output from a previous transaction that is available for selection as an input by the coin selection algorithm. The key is a unique reference to that output, and the value is the amount of unspent value associated with it.
Each key-value pair in the outputsRequested map corresponds to a payment whose value is to be paid for by the coin selection algorithm. The key is a unique reference to a payment recipient, and the value is the amount of money to pay to that recipient.

A coin selection algorithm will select a subset of inputs from inputsAvailable in order to pay for all the outputs in outputsRequested, where:

Inputs selected by the algorithm are included in the inputs set of the generated CoinSelection.
Inputs not selected by the algorithm are included in the inputsRemaining set of the CoinSelectionResult.

The number of inputs that can selected is limited by limit.

The total value of inputsAvailable must be greater than or equal to the total value of outputsRequested, as given by the coinMapValue function.

Since: 1.0.0

Constructors

CoinSelectionParameters
Fields inputsAvailable :: CoinMap i The set of inputs available for selection. outputsRequested :: CoinMap o The set of outputs requested for payment. limit :: CoinSelectionLimit A limit on the number of inputs that can be selected.

Instances

Generic (CoinSelectionParameters i o) Source #
Instance details Defined in Cardano.CoinSelection Associated Types type Rep (CoinSelectionParameters i o) :: Type -> Type # Methods from :: CoinSelectionParameters i o -> Rep (CoinSelectionParameters i o) x # to :: Rep (CoinSelectionParameters i o) x -> CoinSelectionParameters i o #
type Rep (CoinSelectionParameters i o) Source #
Instance details Defined in Cardano.CoinSelection type Rep (CoinSelectionParameters i o) = D1 (MetaData "CoinSelectionParameters" "Cardano.CoinSelection" "cardano-coin-selection-1.0.1-ArWDQ7GeNjh2nML9dPNIzs" False) (C1 (MetaCons "CoinSelectionParameters" PrefixI True) (S1 (MetaSel (Just "inputsAvailable") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (CoinMap i)) :: (S1 (MetaSel (Just "outputsRequested") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (CoinMap o)) :: S1 (MetaSel (Just "limit") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 CoinSelectionLimit))))

data CoinSelectionResult i o Source #

Represents the result of running a coin selection algorithm.

See CoinSelectionAlgorithm.

Since: 1.0.0

Constructors

CoinSelectionResult
Fields coinSelection :: CoinSelection i o The generated coin selection. inputsRemaining :: CoinMap i The set of inputs that were not selected.

Instances

(Eq i, Eq o) => Eq (CoinSelectionResult i o) Source #
Instance details Defined in Cardano.CoinSelection Methods (==) :: CoinSelectionResult i o -> CoinSelectionResult i o -> Bool # (/=) :: CoinSelectionResult i o -> CoinSelectionResult i o -> Bool #
(Show i, Show o) => Show (CoinSelectionResult i o) Source #
Instance details Defined in Cardano.CoinSelection Methods showsPrec :: Int -> CoinSelectionResult i o -> ShowS # show :: CoinSelectionResult i o -> String # showList :: [CoinSelectionResult i o] -> ShowS #

newtype CoinSelectionLimit Source #

Defines an inclusive upper bound on the number of inputs that a CoinSelectionAlgorithm is allowed to select.

Since: 1.0.0

Constructors

CoinSelectionLimit
Fields calculateLimit :: Word16 -> Word16 Calculate the maximum number of inputs allowed for a given number of outputs.

Instances

Generic CoinSelectionLimit Source #
Instance details Defined in Cardano.CoinSelection Associated Types type Rep CoinSelectionLimit :: Type -> Type # Methods from :: CoinSelectionLimit -> Rep CoinSelectionLimit x # to :: Rep CoinSelectionLimit x -> CoinSelectionLimit #
type Rep CoinSelectionLimit Source #
Instance details Defined in Cardano.CoinSelection type Rep CoinSelectionLimit = D1 (MetaData "CoinSelectionLimit" "Cardano.CoinSelection" "cardano-coin-selection-1.0.1-ArWDQ7GeNjh2nML9dPNIzs" True) (C1 (MetaCons "CoinSelectionLimit" PrefixI True) (S1 (MetaSel (Just "calculateLimit") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Word16 -> Word16))))

Coins

data Coin Source #

Represents a non-negative integral amount of currency.

Use coinFromNatural to create a coin from a natural number.

Use coinToNatural to convert a coin into a natural number.

Since: 1.0.0

Instances

Eq Coin Source #
Instance details Defined in Internal.Coin Methods (==) :: Coin -> Coin -> Bool # (/=) :: Coin -> Coin -> Bool #
Ord Coin Source #
Instance details Defined in Internal.Coin Methods compare :: Coin -> Coin -> Ordering # (<) :: Coin -> Coin -> Bool # (<=) :: Coin -> Coin -> Bool # (>) :: Coin -> Coin -> Bool # (>=) :: Coin -> Coin -> Bool # max :: Coin -> Coin -> Coin # min :: Coin -> Coin -> Coin #
Show Coin Source #
Instance details Defined in Internal.Coin Methods showsPrec :: Int -> Coin -> ShowS # show :: Coin -> String # showList :: [Coin] -> ShowS #
Generic Coin Source #
Instance details Defined in Internal.Coin Associated Types type Rep Coin :: Type -> Type # Methods from :: Coin -> Rep Coin x # to :: Rep Coin x -> Coin #
Semigroup Coin Source #
Instance details Defined in Internal.Coin Methods (<>) :: Coin -> Coin -> Coin # sconcat :: NonEmpty Coin -> Coin # stimes :: Integral b => b -> Coin -> Coin #
Monoid Coin Source #
Instance details Defined in Internal.Coin Methods mempty :: Coin # mappend :: Coin -> Coin -> Coin # mconcat :: [Coin] -> Coin #
type Rep Coin Source #
Instance details Defined in Internal.Coin type Rep Coin = D1 (MetaData "Coin" "Internal.Coin" "cardano-coin-selection-1.0.1-ArWDQ7GeNjh2nML9dPNIzs" True) (C1 (MetaCons "Coin" PrefixI True) (S1 (MetaSel (Just "unCoin") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Natural)))

coinFromNatural :: Natural -> Coin Source #

Creates a coin from a natural number.

Since: 1.0.0

coinToNatural :: Coin -> Natural Source #

Converts the given coin into a natural number.

Since: 1.0.0

Coin Maps

newtype CoinMap a Source #

A mapping from unique keys to associated Coin values.

A CoinMap can be used to represent:

a UTxO set, where each key within the map refers to an unspent output from a previous transaction.
a set of inputs to a CoinSelection, where each input is an entry selected from a UTxO set by a CoinSelectionAlgorithm.
a set of outputs for a CoinSelection, where each key within the map refers to the address of a payment recipient.

A CoinMap can be constructed with the coinMapFromList function.

The total value of a CoinMap is given by the coinMapValue function.

Since: 1.0.0

Constructors

CoinMap
Fields unCoinMap :: Map a Coin

Instances

Foldable CoinMap Source #
Instance details Defined in Cardano.CoinSelection Methods fold :: Monoid m => CoinMap m -> m # foldMap :: Monoid m => (a -> m) -> CoinMap a -> m # foldr :: (a -> b -> b) -> b -> CoinMap a -> b # foldr' :: (a -> b -> b) -> b -> CoinMap a -> b # foldl :: (b -> a -> b) -> b -> CoinMap a -> b # foldl' :: (b -> a -> b) -> b -> CoinMap a -> b # foldr1 :: (a -> a -> a) -> CoinMap a -> a # foldl1 :: (a -> a -> a) -> CoinMap a -> a # toList :: CoinMap a -> [a] # null :: CoinMap a -> Bool # length :: CoinMap a -> Int # elem :: Eq a => a -> CoinMap a -> Bool # maximum :: Ord a => CoinMap a -> a # minimum :: Ord a => CoinMap a -> a # sum :: Num a => CoinMap a -> a # product :: Num a => CoinMap a -> a #
Eq a => Eq (CoinMap a) Source #
Instance details Defined in Cardano.CoinSelection Methods (==) :: CoinMap a -> CoinMap a -> Bool # (/=) :: CoinMap a -> CoinMap a -> Bool #
Show a => Show (CoinMap a) Source #
Instance details Defined in Cardano.CoinSelection Methods showsPrec :: Int -> CoinMap a -> ShowS # show :: CoinMap a -> String # showList :: [CoinMap a] -> ShowS #
Generic (CoinMap a) Source #
Instance details Defined in Cardano.CoinSelection Associated Types type Rep (CoinMap a) :: Type -> Type # Methods from :: CoinMap a -> Rep (CoinMap a) x # to :: Rep (CoinMap a) x -> CoinMap a #
Ord a => Semigroup (CoinMap a) Source #
Instance details Defined in Cardano.CoinSelection Methods (<>) :: CoinMap a -> CoinMap a -> CoinMap a # sconcat :: NonEmpty (CoinMap a) -> CoinMap a # stimes :: Integral b => b -> CoinMap a -> CoinMap a #
Ord a => Monoid (CoinMap a) Source #
Instance details Defined in Cardano.CoinSelection Methods mempty :: CoinMap a # mappend :: CoinMap a -> CoinMap a -> CoinMap a # mconcat :: [CoinMap a] -> CoinMap a #
type Rep (CoinMap a) Source #
Instance details Defined in Cardano.CoinSelection type Rep (CoinMap a) = D1 (MetaData "CoinMap" "Cardano.CoinSelection" "cardano-coin-selection-1.0.1-ArWDQ7GeNjh2nML9dPNIzs" True) (C1 (MetaCons "CoinMap" PrefixI True) (S1 (MetaSel (Just "unCoinMap") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Map a Coin))))

data CoinMapEntry a Source #

An entry for a CoinMap.

Since: 1.0.0

Constructors

CoinMapEntry
Fields entryKey :: a The unique key associated with this entry. entryValue :: Coin The coin value associated with this entry.

Instances

Eq a => Eq (CoinMapEntry a) Source #
Instance details Defined in Cardano.CoinSelection Methods (==) :: CoinMapEntry a -> CoinMapEntry a -> Bool # (/=) :: CoinMapEntry a -> CoinMapEntry a -> Bool #
Ord a => Ord (CoinMapEntry a) Source #
Instance details Defined in Cardano.CoinSelection Methods compare :: CoinMapEntry a -> CoinMapEntry a -> Ordering # (<) :: CoinMapEntry a -> CoinMapEntry a -> Bool # (<=) :: CoinMapEntry a -> CoinMapEntry a -> Bool # (>) :: CoinMapEntry a -> CoinMapEntry a -> Bool # (>=) :: CoinMapEntry a -> CoinMapEntry a -> Bool # max :: CoinMapEntry a -> CoinMapEntry a -> CoinMapEntry a # min :: CoinMapEntry a -> CoinMapEntry a -> CoinMapEntry a #
Show a => Show (CoinMapEntry a) Source #
Instance details Defined in Cardano.CoinSelection Methods showsPrec :: Int -> CoinMapEntry a -> ShowS # show :: CoinMapEntry a -> String # showList :: [CoinMapEntry a] -> ShowS #
Generic (CoinMapEntry a) Source #
Instance details Defined in Cardano.CoinSelection Associated Types type Rep (CoinMapEntry a) :: Type -> Type # Methods from :: CoinMapEntry a -> Rep (CoinMapEntry a) x # to :: Rep (CoinMapEntry a) x -> CoinMapEntry a #
type Rep (CoinMapEntry a) Source #
Instance details Defined in Cardano.CoinSelection type Rep (CoinMapEntry a) = D1 (MetaData "CoinMapEntry" "Cardano.CoinSelection" "cardano-coin-selection-1.0.1-ArWDQ7GeNjh2nML9dPNIzs" False) (C1 (MetaCons "CoinMapEntry" PrefixI True) (S1 (MetaSel (Just "entryKey") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 a) :*: S1 (MetaSel (Just "entryValue") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Coin)))

coinMapFromList :: Ord a => [CoinMapEntry a] -> CoinMap a Source #

Constructs a CoinMap from a list of entries.

See CoinMapEntry.

Since: 1.0.0

coinMapToList :: CoinMap a -> [CoinMapEntry a] Source #

Converts a CoinMap to a list of entries.

See CoinMapEntry.

Since: 1.0.0

coinMapValue :: CoinMap a -> Coin Source #

Calculates the total coin value associated with a CoinMap.

Since: 1.0.0

Coin Selection Errors

data CoinSelectionError Source #

Represents the set of possible failures that can occur when attempting to produce a CoinSelection with a CoinSelectionAlgorithm.

See selectCoins.

Since: 1.0.0

Constructors

InputValueInsufficient InputValueInsufficientError
InputCountInsufficient InputCountInsufficientError
InputLimitExceeded InputLimitExceededError
InputsExhausted InputsExhaustedError

Instances

Eq CoinSelectionError Source #
Instance details Defined in Cardano.CoinSelection Methods (==) :: CoinSelectionError -> CoinSelectionError -> Bool # (/=) :: CoinSelectionError -> CoinSelectionError -> Bool #
Show CoinSelectionError Source #
Instance details Defined in Cardano.CoinSelection Methods showsPrec :: Int -> CoinSelectionError -> ShowS # show :: CoinSelectionError -> String # showList :: [CoinSelectionError] -> ShowS #

data InputValueInsufficientError Source #

Indicates that the total value of inputsAvailable is less than the total value of outputsRequested, making it impossible to cover all payments, regardless of which algorithm is chosen.

Since: 1.0.0

Constructors

InputValueInsufficientError
Fields inputValueAvailable :: Coin The total value of `inputsAvailable`. inputValueRequired :: Coin The total value of `outputsRequested`.

Instances

Eq InputValueInsufficientError Source #
Instance details Defined in Cardano.CoinSelection Methods (==) :: InputValueInsufficientError -> InputValueInsufficientError -> Bool # (/=) :: InputValueInsufficientError -> InputValueInsufficientError -> Bool #
Show InputValueInsufficientError Source #
Instance details Defined in Cardano.CoinSelection Methods showsPrec :: Int -> InputValueInsufficientError -> ShowS # show :: InputValueInsufficientError -> String # showList :: [InputValueInsufficientError] -> ShowS #

data InputCountInsufficientError Source #

Indicates that the total count of entries in inputsAvailable is fewer than required by the algorithm. The number required depends on the particular algorithm implementation.

Since: 1.0.0

Constructors

InputCountInsufficientError
Fields inputCountAvailable :: Natural The number of entries in `inputsAvailable`. inputCountRequired :: Natural The number of entries required.

Instances

Eq InputCountInsufficientError Source #
Instance details Defined in Cardano.CoinSelection Methods (==) :: InputCountInsufficientError -> InputCountInsufficientError -> Bool # (/=) :: InputCountInsufficientError -> InputCountInsufficientError -> Bool #
Show InputCountInsufficientError Source #
Instance details Defined in Cardano.CoinSelection Methods showsPrec :: Int -> InputCountInsufficientError -> ShowS # show :: InputCountInsufficientError -> String # showList :: [InputCountInsufficientError] -> ShowS #

newtype InputLimitExceededError Source #

Indicates that the coin selection algorithm is unable to cover the total value of outputsRequested without exceeding the maximum number of inputs defined by limit.

See calculateLimit.

Since: 1.0.0

Constructors

InputLimitExceededError
Fields calculatedInputLimit :: Word16

Instances

Eq InputLimitExceededError Source #
Instance details Defined in Cardano.CoinSelection Methods (==) :: InputLimitExceededError -> InputLimitExceededError -> Bool # (/=) :: InputLimitExceededError -> InputLimitExceededError -> Bool #
Show InputLimitExceededError Source #
Instance details Defined in Cardano.CoinSelection Methods showsPrec :: Int -> InputLimitExceededError -> ShowS # show :: InputLimitExceededError -> String # showList :: [InputLimitExceededError] -> ShowS #

data InputsExhaustedError Source #

Indicates that all available entries in inputsAvailable were depleted before all the payments in outputsRequested could be paid for.

This condition can occur even if the total value of inputsAvailable is greater than or equal to the total value of outputsRequested, due to differences in the way that algorithms select inputs.

Since: 1.0.0

Constructors

InputsExhaustedError

Instances

Eq InputsExhaustedError Source #
Instance details Defined in Cardano.CoinSelection Methods (==) :: InputsExhaustedError -> InputsExhaustedError -> Bool # (/=) :: InputsExhaustedError -> InputsExhaustedError -> Bool #
Show InputsExhaustedError Source #
Instance details Defined in Cardano.CoinSelection Methods showsPrec :: Int -> InputsExhaustedError -> ShowS # show :: InputsExhaustedError -> String # showList :: [InputsExhaustedError] -> ShowS #