Copyright	© 2018-2021 IOHK 2025 GYELD GMBH
License	Apache-2.0
Safe Haskell	Safe-Inferred
Language	GHC2021

GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal

Contents

Type
Construction
Deconstruction
Folding
Modification
Filtering and partitioning
Queries
Set operations
Selection
Value categorization
Utilities
Invariant

Description

Modified by: GeniusYield

Originally from: Cardano.CoinSelection.UTxOIndex.Internal.

Provides internal functions for the UTxOIndex type, which indexes a UTxO set by asset identifier.

The index makes it possible to efficiently compute the subset of a UTxO set containing a particular asset, or to select just a single UTxO containing a particular asset, without having to search linearly through the entire UTxO set.

See the documentation for UTxOIndex for more details.

Synopsis

data UTxOIndex u
empty ∷ UTxOIndex u
singleton ∷ Ord u ⇒ u → GYValue → UTxOIndex u
fromSequence ∷ (Foldable f, Ord u) ⇒ f (u, GYValue) → UTxOIndex u
fromMap ∷ Ord u ⇒ Map u GYValue → UTxOIndex u
toList ∷ UTxOIndex u → [(u, GYValue)]
toMap ∷ UTxOIndex u → Map u GYValue
fold ∷ (a → u → GYValue → a) → a → UTxOIndex u → a
insert ∷ Ord u ⇒ u → GYValue → UTxOIndex u → UTxOIndex u
insertMany ∷ (Foldable f, Ord u) ⇒ f (u, GYValue) → UTxOIndex u → UTxOIndex u
delete ∷ ∀ u. Ord u ⇒ u → UTxOIndex u → UTxOIndex u
deleteMany ∷ (Foldable f, Ord u) ⇒ f u → UTxOIndex u → UTxOIndex u
filter ∷ Ord u ⇒ (u → Bool) → UTxOIndex u → UTxOIndex u
partition ∷ Ord u ⇒ (u → Bool) → UTxOIndex u → (UTxOIndex u, UTxOIndex u)
assets ∷ UTxOIndex u → Set GYAssetClass
balance ∷ UTxOIndex u → GYValue
lookup ∷ Ord u ⇒ u → UTxOIndex u → Maybe GYValue
member ∷ Ord u ⇒ u → UTxOIndex u → Bool
null ∷ UTxOIndex u → Bool
size ∷ UTxOIndex u → Int
difference ∷ Ord u ⇒ UTxOIndex u → UTxOIndex u → UTxOIndex u
disjoint ∷ Ord u ⇒ UTxOIndex u → UTxOIndex u → Bool
data SelectionFilter asset
- = SelectSingleton asset
- | SelectPairWith asset
- | SelectAnyWith asset
- | SelectAny
selectRandom ∷ ∀ m u. (MonadRandom m, Ord u) ⇒ UTxOIndex u → SelectionFilter GYAssetClass → m (Maybe ((u, GYValue), UTxOIndex u))
selectRandomWithPriority ∷ (MonadRandom m, Ord u) ⇒ UTxOIndex u → NonEmpty (SelectionFilter GYAssetClass) → m (Maybe ((u, GYValue), UTxOIndex u))
data ValueCategory asset
- = ValueWithNoAssets
- | ValueWithOneAsset asset
- | ValueWithTwoAssets (asset, asset)
- | ValueWithMultipleAssets (Set asset)
categorizeValue ∷ GYValue → ValueCategory GYAssetClass
selectRandomSetMember ∷ MonadRandom m ⇒ Set a → m (Maybe a)
data InvariantStatus
- = InvariantHolds
- | InvariantBalanceError BalanceError
- | InvariantIndexIncomplete
- | InvariantIndexNonMinimal
- | InvariantIndexInconsistent
- | InvariantAssetsInconsistent
checkInvariant ∷ Ord u ⇒ UTxOIndex u → InvariantStatus

Type

data UTxOIndex u #

A UTxO set that is indexed by asset identifier.

The index provides a mapping from assets to subsets of the UTxO set.

A UTxO appears in the set for a particular asset if and only if its associated value has a non-zero quantity of that asset.

The index makes it possible to efficiently compute the subset of a UTxO set containing a particular asset, or to select just a single UTxO containing a particular asset, without having to search linearly through the entire UTxO set.

The index also keeps track of the current UTxO balance of all assets, making it possible to efficiently look up the total quantity of a particular asset without having to sum across the entire UTxO set.

The UTxO index data structure has an invariant that can be checked with the checkInvariant function.

Instances

Instances details

Generic (UTxOIndex u) #
Instance details Defined in GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal Associated Types type Rep (UTxOIndex u) ∷ Type → Type # Methods from ∷ UTxOIndex u → Rep (UTxOIndex u) x # to ∷ Rep (UTxOIndex u) x → UTxOIndex u #
Show u ⇒ Show (UTxOIndex u) #
Instance details Defined in GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal Methods showsPrec ∷ Int → UTxOIndex u → ShowS # show ∷ UTxOIndex u → String # showList ∷ [UTxOIndex u] → ShowS #
Eq u ⇒ Eq (UTxOIndex u) #
Instance details Defined in GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal Methods (==) ∷ UTxOIndex u → UTxOIndex u → Bool # (/=) ∷ UTxOIndex u → UTxOIndex u → Bool #
type Rep (UTxOIndex u) #
Instance details Defined in GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal type Rep (UTxOIndex u) = D1 ('MetaData "UTxOIndex" "GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal" "atlas-cardano-0.13.0-inplace" 'False) (C1 ('MetaCons "UTxOIndex" 'PrefixI 'True) ((S1 ('MetaSel ('Just "indexAll") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (MonoidMap GYAssetClass (Set u))) :: S1 ('MetaSel ('Just "indexSingletons") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (MonoidMap GYAssetClass (Set u)))) :: (S1 ('MetaSel ('Just "indexPairs") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (MonoidMap GYAssetClass (Set u))) :: (S1 ('MetaSel ('Just "balance") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 GYValue) :: S1 ('MetaSel ('Just "universe") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (Map u GYValue))))))

Construction

empty ∷ UTxOIndex u #

An index with no entries.

singleton ∷ Ord u ⇒ u → GYValue → UTxOIndex u #

Creates a singleton index from the specified UTxO identifier and value.

fromSequence ∷ (Foldable f, Ord u) ⇒ f (u, GYValue) → UTxOIndex u #

Constructs an index from a sequence of entries.

Note that this operation is potentially expensive as it must construct an index from scratch, and therefore should only be used sparingly.

If the given sequence contains more than one mapping for the same UTxO identifier, the mapping that appears latest in the sequence will take precedence, and all others will be ignored.

fromMap ∷ Ord u ⇒ Map u GYValue → UTxOIndex u #

Constructs an index from a map.

Note that this operation is potentially expensive as it must construct an index from scratch, and therefore should only be used sparingly.

Satisfies the following property:

fromMap ≡ fromSequence . toList

Deconstruction

toList ∷ UTxOIndex u → [(u, GYValue)] #

Converts an index to a list of its constituent entries.

Consider using fold if your goal is to consume all entries in the output.

toMap ∷ UTxOIndex u → Map u GYValue #

Converts an index into a map.

Consider using fold if your goal is to consume all entries in the output.

Folding

fold ∷ (a → u → GYValue → a) → a → UTxOIndex u → a #

Folds strictly over the constituent entries of an index.

Modification

insert ∷ Ord u ⇒ u → GYValue → UTxOIndex u → UTxOIndex u #

Inserts an entry that maps the given UTxO identifier to the given value.

If the index has an existing value for the specified UTxO identifier, the value referred to by that identifier will be replaced with the specified value.

insertMany ∷ (Foldable f, Ord u) ⇒ f (u, GYValue) → UTxOIndex u → UTxOIndex u #

Inserts multiple entries into an index.

See insert.

delete ∷ ∀ u. Ord u ⇒ u → UTxOIndex u → UTxOIndex u #

Deletes the entry corresponding to the given UTxO identifier.

If the index has no existing entry for the specified identifier, the result of applying this function will be equivalent to the identity function.

deleteMany ∷ (Foldable f, Ord u) ⇒ f u → UTxOIndex u → UTxOIndex u #

Deletes multiple entries from an index.

See delete.

Filtering and partitioning

filter ∷ Ord u ⇒ (u → Bool) → UTxOIndex u → UTxOIndex u #

Filters an index.

partition ∷ Ord u ⇒ (u → Bool) → UTxOIndex u → (UTxOIndex u, UTxOIndex u) #

Partitions an index.

Queries

assets ∷ UTxOIndex u → Set GYAssetClass #

Returns the complete set of all assets contained in an index.

balance ∷ UTxOIndex u → GYValue #

lookup ∷ Ord u ⇒ u → UTxOIndex u → Maybe GYValue #

Returns the value corresponding to the given UTxO identifier.

If the index has no such identifier, this function returns Nothing.

member ∷ Ord u ⇒ u → UTxOIndex u → Bool #

Returns True if (and only if) the index has an entry for the given UTxO identifier.

null ∷ UTxOIndex u → Bool #

Returns True if (and only if) the index is empty.

size ∷ UTxOIndex u → Int #

Returns the total number of UTxO entries held within the index.

Set operations

difference ∷ Ord u ⇒ UTxOIndex u → UTxOIndex u → UTxOIndex u #

Creates a new index by subtracting the second index from the first.

This operation is fast if the intersection of the first and second indices is small relative to the size of the first index.

disjoint ∷ Ord u ⇒ UTxOIndex u → UTxOIndex u → Bool #

Indicates whether a pair of UTxO indices are disjoint.

Selection

data SelectionFilter asset #

Specifies a filter for selecting UTxO entries.

Constructors

SelectSingleton asset	Matches UTxOs that contain only the given asset and no other assets.
SelectPairWith asset	Matches UTxOs that contain the given asset and exactly one other asset.
SelectAnyWith asset	Matches UTxOs that contain the given asset and any number of other assets.
SelectAny	Matches all UTxOs regardless of what assets they contain.

Instances

Instances details

Foldable SelectionFilter #
Instance details Defined in GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal Methods fold ∷ Monoid m ⇒ SelectionFilter m → m # foldMap ∷ Monoid m ⇒ (a → m) → SelectionFilter a → m # foldMap' ∷ Monoid m ⇒ (a → m) → SelectionFilter a → m # foldr ∷ (a → b → b) → b → SelectionFilter a → b # foldr' ∷ (a → b → b) → b → SelectionFilter a → b # foldl ∷ (b → a → b) → b → SelectionFilter a → b # foldl' ∷ (b → a → b) → b → SelectionFilter a → b # foldr1 ∷ (a → a → a) → SelectionFilter a → a # foldl1 ∷ (a → a → a) → SelectionFilter a → a # toList ∷ SelectionFilter a → [a] # null ∷ SelectionFilter a → Bool # length ∷ SelectionFilter a → Int # elem ∷ Eq a ⇒ a → SelectionFilter a → Bool # maximum ∷ Ord a ⇒ SelectionFilter a → a # minimum ∷ Ord a ⇒ SelectionFilter a → a # sum ∷ Num a ⇒ SelectionFilter a → a # product ∷ Num a ⇒ SelectionFilter a → a #
Traversable SelectionFilter #
Instance details Defined in GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal Methods traverse ∷ Applicative f ⇒ (a → f b) → SelectionFilter a → f (SelectionFilter b) # sequenceA ∷ Applicative f ⇒ SelectionFilter (f a) → f (SelectionFilter a) # mapM ∷ Monad m ⇒ (a → m b) → SelectionFilter a → m (SelectionFilter b) # sequence ∷ Monad m ⇒ SelectionFilter (m a) → m (SelectionFilter a) #
Functor SelectionFilter #
Instance details Defined in GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal Methods fmap ∷ (a → b) → SelectionFilter a → SelectionFilter b # (<$) ∷ a → SelectionFilter b → SelectionFilter a #
Show asset ⇒ Show (SelectionFilter asset) #
Instance details Defined in GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal Methods showsPrec ∷ Int → SelectionFilter asset → ShowS # show ∷ SelectionFilter asset → String # showList ∷ [SelectionFilter asset] → ShowS #
Eq asset ⇒ Eq (SelectionFilter asset) #
Instance details Defined in GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal Methods (==) ∷ SelectionFilter asset → SelectionFilter asset → Bool # (/=) ∷ SelectionFilter asset → SelectionFilter asset → Bool #

selectRandom ∷ ∀ m u. (MonadRandom m, Ord u) ⇒ UTxOIndex u → SelectionFilter GYAssetClass → m (Maybe ((u, GYValue), UTxOIndex u)) #

Selects an entry at random from the index according to the given filter.

Returns the selected entry and an updated index with the entry removed.

Returns Nothing if there were no matching entries.

selectRandomWithPriority #

Arguments

∷ (MonadRandom m, Ord u)
⇒ UTxOIndex u
→ NonEmpty (SelectionFilter GYAssetClass)	A list of selection filters to be traversed in descending order of priority, from left to right.
→ m (Maybe ((u, GYValue), UTxOIndex u))

Selects an entry at random from the index according to the given filters.

This function traverses the specified list of filters in descending order of priority, from left to right.

When considering a particular filter:

if the function is able to select a UTxO entry that matches, it terminates with that entry and an updated index with the entry removed.
if the function is not able to select a UTxO entry that matches, it traverses to the next filter available.

This function returns Nothing if (and only if) it traverses the entire list of filters without successfully selecting a UTxO entry.

Value categorization

data ValueCategory asset #

Represents different categories of value.

Constructors

ValueWithNoAssets
ValueWithOneAsset asset
ValueWithTwoAssets (asset, asset)
ValueWithMultipleAssets (Set asset)

Instances

Instances details

Show asset ⇒ Show (ValueCategory asset) #
Instance details Defined in GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal Methods showsPrec ∷ Int → ValueCategory asset → ShowS # show ∷ ValueCategory asset → String # showList ∷ [ValueCategory asset] → ShowS #
Eq asset ⇒ Eq (ValueCategory asset) #
Instance details Defined in GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal Methods (==) ∷ ValueCategory asset → ValueCategory asset → Bool # (/=) ∷ ValueCategory asset → ValueCategory asset → Bool #

categorizeValue ∷ GYValue → ValueCategory GYAssetClass #

Categorizes a value by how many assets it contains.

Utilities

selectRandomSetMember ∷ MonadRandom m ⇒ Set a → m (Maybe a) #

Selects an element at random from the given set.

Returns Nothing if (and only if) the given set is empty.

Invariant

data InvariantStatus #

The result of checking the invariant with the checkInvariant function.

Constructors

InvariantHolds	Indicates a successful check of the invariant.
InvariantBalanceError BalanceError	Indicates that the cached `balance` value is incorrect.
InvariantIndexIncomplete	Indicates that the `index` is missing one or more entries.
InvariantIndexNonMinimal	Indicates that the `index` has one or more unnecessary entries.
InvariantIndexInconsistent	Indicates that the index sets are not consistent.
InvariantAssetsInconsistent	Indicates that the `index` and the cached `balance` value disagree about which assets are included.

Instances

Instances details

Show InvariantStatus #
Instance details Defined in GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal Methods showsPrec ∷ Int → InvariantStatus → ShowS # show ∷ InvariantStatus → String # showList ∷ [InvariantStatus] → ShowS #
Eq InvariantStatus #
Instance details Defined in GeniusYield.Transaction.CoinSelection.UTxOIndex.Internal Methods (==) ∷ InvariantStatus → InvariantStatus → Bool # (/=) ∷ InvariantStatus → InvariantStatus → Bool #

checkInvariant ∷ Ord u ⇒ UTxOIndex u → InvariantStatus #

Checks whether or not the invariant holds.