cardano-wallet-core-2022.7.1: The Wallet Backend for a Cardano node.
Copyright © 2018-2021 IOHK
License Apache-2.0
Safe Haskell None
Language Haskell2010

Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

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

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

( Read u, Ord u) => Read ( UTxOIndex u) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

Show u => Show ( UTxOIndex u) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

Generic ( UTxOIndex u) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

Associated Types

type Rep ( UTxOIndex u) :: Type -> Type Source #

NFData u => NFData ( UTxOIndex u) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

type Rep ( UTxOIndex u) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

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.

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

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

Foldable SelectionFilter Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

Traversable SelectionFilter Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

Eq asset => Eq ( SelectionFilter asset) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

Show asset => Show ( SelectionFilter asset) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

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.

Instances

Instances details
Eq Asset Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

Ord Asset Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

Read Asset Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

Show Asset Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

Generic Asset Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

NFData Asset Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.UTxOIndex.Internal

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

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.

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

Checks whether or not the invariant holds.