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

Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

Contents

Type
Construction
Deconstruction
Folding
Modification
Filtering and partitioning
Queries
Set operations
Selection
Assets
Token bundle categorization
Utilities
Invariant

Description

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 -> TokenBundle -> UTxOIndex u
fromSequence :: ( Foldable f, Ord u) => f (u, TokenBundle ) -> UTxOIndex u
fromMap :: Ord u => Map u TokenBundle -> UTxOIndex u
toList :: UTxOIndex u -> [(u, TokenBundle )]
toMap :: UTxOIndex u -> Map u TokenBundle
fold :: (a -> u -> TokenBundle -> a) -> a -> UTxOIndex u -> a
insert :: Ord u => u -> TokenBundle -> UTxOIndex u -> UTxOIndex u
insertMany :: ( Foldable f, Ord u) => f (u, TokenBundle ) -> UTxOIndex u -> UTxOIndex u
delete :: forall 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 Asset
balance :: UTxOIndex u -> TokenBundle
lookup :: Ord u => u -> UTxOIndex u -> Maybe TokenBundle
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 :: forall m u. ( MonadRandom m, Ord u) => UTxOIndex u -> SelectionFilter Asset -> m ( Maybe ((u, TokenBundle ), UTxOIndex u))
selectRandomWithPriority :: ( MonadRandom m, Ord u) => UTxOIndex u -> NonEmpty ( SelectionFilter Asset ) -> m ( Maybe ((u, TokenBundle ), UTxOIndex u))
data Asset
- = AssetLovelace
- | Asset AssetId
tokenBundleAssets :: TokenBundle -> Set Asset
tokenBundleAssetCount :: TokenBundle -> Int
tokenBundleHasAsset :: TokenBundle -> Asset -> Bool
data BundleCategory asset
- = BundleWithNoAssets
- | BundleWithOneAsset asset
- | BundleWithTwoAssets (asset, asset)
- | BundleWithMultipleAssets ( Set asset)
categorizeTokenBundle :: TokenBundle -> BundleCategory Asset
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 Source #

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

Eq u => Eq ( UTxOIndex u) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Methods (==) :: UTxOIndex u -> UTxOIndex u -> Bool Source # (/=) :: UTxOIndex u -> UTxOIndex u -> Bool Source #
( Read u, Ord u) => Read ( UTxOIndex u) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Methods readsPrec :: Int -> ReadS ( UTxOIndex u) Source # readList :: ReadS [ UTxOIndex u] Source # readPrec :: ReadPrec ( UTxOIndex u) Source # readListPrec :: ReadPrec [ UTxOIndex u] Source #
Show u => Show ( UTxOIndex u) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Methods showsPrec :: Int -> UTxOIndex u -> ShowS Source # show :: UTxOIndex u -> String Source # showList :: [ UTxOIndex u] -> ShowS Source #
Generic ( UTxOIndex u) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Associated Types type Rep ( UTxOIndex u) :: Type -> Type Source # Methods from :: UTxOIndex u -> Rep ( UTxOIndex u) x Source # to :: Rep ( UTxOIndex u) x -> UTxOIndex u Source #
NFData u => NFData ( UTxOIndex u) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Methods rnf :: UTxOIndex u -> () Source #
type Rep ( UTxOIndex u) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal type Rep ( UTxOIndex u) = D1 (' MetaData "UTxOIndex" "Cardano.Wallet.Primitive.Types.UTxOIndex.Internal" "cardano-wallet-core-2022.7.1-AGKhlyz9liLKN3QqZD1gj" ' False ) ( C1 (' MetaCons "UTxOIndex" ' PrefixI ' True ) (( S1 (' MetaSel (' Just "indexAll") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 ( Map Asset ( NonEmptySet u))) :: S1 (' MetaSel (' Just "indexSingletons") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 ( Map Asset ( NonEmptySet u)))) :: ( S1 (' MetaSel (' Just "indexPairs") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 ( Map Asset ( NonEmptySet u))) :: ( S1 (' MetaSel (' Just "balance") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 TokenBundle ) :: S1 (' MetaSel (' Just "universe") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 ( Map u TokenBundle ))))))

Construction

empty :: UTxOIndex u Source #

An index with no entries.

singleton :: Ord u => u -> TokenBundle -> UTxOIndex u Source #

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

fromSequence :: ( Foldable f, Ord u) => f (u, TokenBundle ) -> UTxOIndex u Source #

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 TokenBundle -> UTxOIndex u Source #

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.

Deconstruction

toList :: UTxOIndex u -> [(u, TokenBundle )] Source #

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 TokenBundle Source #

Converts an index into a map.

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

Folding

fold :: (a -> u -> TokenBundle -> a) -> a -> UTxOIndex u -> a Source #

Folds strictly over the constituent entries of an index.

Modification

insert :: Ord u => u -> TokenBundle -> UTxOIndex u -> UTxOIndex u Source #

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, TokenBundle ) -> UTxOIndex u -> UTxOIndex u Source #

Inserts multiple entries into an index.

See insert .

delete :: forall u. Ord u => u -> UTxOIndex u -> UTxOIndex u Source #

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 Source #

Deletes multiple entries from an index.

See delete .

Filtering and partitioning

filter :: Ord u => (u -> Bool ) -> UTxOIndex u -> UTxOIndex u Source #

Filters an index.

partition :: Ord u => (u -> Bool ) -> UTxOIndex u -> ( UTxOIndex u, UTxOIndex u) Source #

Partitions an index.

Queries

assets :: UTxOIndex u -> Set Asset Source #

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

balance :: UTxOIndex u -> TokenBundle Source #

lookup :: Ord u => u -> UTxOIndex u -> Maybe TokenBundle Source #

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 Source #

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

null :: UTxOIndex u -> Bool Source #

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

size :: UTxOIndex u -> Int Source #

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

Set operations

difference :: Ord u => UTxOIndex u -> UTxOIndex u -> UTxOIndex u Source #

disjoint :: Ord u => UTxOIndex u -> UTxOIndex u -> Bool Source #

Indicates whether a pair of UTxO indices are disjoint.

Selection

data SelectionFilter asset Source #

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

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

selectRandom :: forall m u. ( MonadRandom m, Ord u) => UTxOIndex u -> SelectionFilter Asset -> m ( Maybe ((u, TokenBundle ), UTxOIndex u)) Source #

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 Source #

Arguments

:: ( MonadRandom m, Ord u)
=> UTxOIndex u
-> NonEmpty ( SelectionFilter Asset )	A list of selection filters to be traversed in descending order of priority, from left to right.
-> m ( Maybe ((u, TokenBundle ), 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.

Assets

data Asset Source #

A type capable of representing any asset, including both ada and non-ada assets.

TODO: ADP-1449 Move this type away from the UTxOIndex module and replace all usages of it with a type parameter.

Constructors

AssetLovelace
Asset AssetId

Instances

Instances details

Eq Asset Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Methods (==) :: Asset -> Asset -> Bool Source # (/=) :: Asset -> Asset -> Bool Source #
Ord Asset Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Methods compare :: Asset -> Asset -> Ordering Source # (<) :: Asset -> Asset -> Bool Source # (<=) :: Asset -> Asset -> Bool Source # (>) :: Asset -> Asset -> Bool Source # (>=) :: Asset -> Asset -> Bool Source # max :: Asset -> Asset -> Asset Source # min :: Asset -> Asset -> Asset Source #
Read Asset Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Methods readsPrec :: Int -> ReadS Asset Source # readList :: ReadS [ Asset ] Source # readPrec :: ReadPrec Asset Source # readListPrec :: ReadPrec [ Asset ] Source #
Show Asset Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Methods showsPrec :: Int -> Asset -> ShowS Source # show :: Asset -> String Source # showList :: [ Asset ] -> ShowS Source #
Generic Asset Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Associated Types type Rep Asset :: Type -> Type Source # Methods from :: Asset -> Rep Asset x Source # to :: Rep Asset x -> Asset Source #
NFData Asset Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Methods rnf :: Asset -> () Source #
type Rep Asset Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal type Rep Asset = D1 (' MetaData "Asset" "Cardano.Wallet.Primitive.Types.UTxOIndex.Internal" "cardano-wallet-core-2022.7.1-AGKhlyz9liLKN3QqZD1gj" ' False ) ( C1 (' MetaCons "AssetLovelace" ' PrefixI ' False ) ( U1 :: Type -> Type ) :+: C1 (' MetaCons "Asset" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 AssetId )))

tokenBundleAssets :: TokenBundle -> Set Asset Source #

Returns the set of assets associated with a given TokenBundle .

Both ada and non-ada assets are included in the set returned.

TODO: ADP-1449 Move this function away from the UTxOIndex module once the type of assets has been generalized.

tokenBundleAssetCount :: TokenBundle -> Int Source #

Returns the number of assets associated with a given TokenBundle .

Both ada and non-ada assets are included in the total count returned.

TODO: ADP-1449 Move this function away from the UTxOIndex module once the type of assets has been generalized.

tokenBundleHasAsset :: TokenBundle -> Asset -> Bool Source #

Indicates whether or not a given bundle includes a given asset.

Both ada and non-ada assets can be queried.

TODO: ADP-1449 Move this function away from the UTxOIndex module once the type of assets has been generalized.

Token bundle categorization

data BundleCategory asset Source #

Represents different categories of token bundles.

Constructors

BundleWithNoAssets
BundleWithOneAsset asset
BundleWithTwoAssets (asset, asset)
BundleWithMultipleAssets ( Set asset)

Instances

Instances details

Eq asset => Eq ( BundleCategory asset) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Methods (==) :: BundleCategory asset -> BundleCategory asset -> Bool Source # (/=) :: BundleCategory asset -> BundleCategory asset -> Bool Source #
Show asset => Show ( BundleCategory asset) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Methods showsPrec :: Int -> BundleCategory asset -> ShowS Source # show :: BundleCategory asset -> String Source # showList :: [ BundleCategory asset] -> ShowS Source #

categorizeTokenBundle :: TokenBundle -> BundleCategory Asset Source #

Categorizes a token bundle by how many assets it contains.

Utilities

selectRandomSetMember :: MonadRandom m => Set a -> m ( Maybe a) Source #

Selects an element at random from the given set.

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

Invariant

data InvariantStatus Source #

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

Eq InvariantStatus Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Methods (==) :: InvariantStatus -> InvariantStatus -> Bool Source # (/=) :: InvariantStatus -> InvariantStatus -> Bool Source #
Show InvariantStatus Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal Methods showsPrec :: Int -> InvariantStatus -> ShowS Source # show :: InvariantStatus -> String Source # showList :: [ InvariantStatus ] -> ShowS Source #

checkInvariant :: Ord u => UTxOIndex u -> InvariantStatus Source #

Checks whether or not the invariant holds.