| Copyright | © 2018-2021 IOHK |
|---|---|
| License | Apache-2.0 |
| Safe Haskell | None |
| Language | Haskell2010 |
Cardano.Wallet.Primitive.Types.UTxOIndex
Description
Provides 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.
This module is meant to be imported qualified. For example:
>>>import qualified Cardano.Wallet.Primitive.Types.UTxOIndex as UTxOIndex
Synopsis
- data UTxOIndex u
- empty :: UTxOIndex u
- singleton :: Ord u => u -> TokenBundle -> UTxOIndex u
- fromMap :: Ord u => Map u TokenBundle -> UTxOIndex u
- fromSequence :: ( Foldable f, Ord u) => f (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 Asset
-
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))
Type
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
Construction
singleton :: Ord u => u -> TokenBundle -> UTxOIndex u Source #
Creates a singleton index from the specified UTxO identifier and value.
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.
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.
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
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.
Set operations
disjoint :: Ord u => UTxOIndex u -> UTxOIndex u -> Bool Source #
Indicates whether a pair of UTxO indices are disjoint.
Selection
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
| Eq Asset Source # | |
| Ord Asset Source # | |
| Read Asset Source # | |
| Show Asset Source # | |
| Generic Asset Source # | |
| NFData Asset Source # | |
| type Rep Asset Source # | |
|
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
)))
|
|
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
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.