cardano-wallet-core-2022.7.1: The Wallet Backend for a Cardano node.
Safe Haskell None
Language Haskell2010

Cardano.Wallet.Primitive.Types.TokenBundle

Description

Provides the TokenBundle type, which combines a Coin (lovelace) value with a map of named token quantities, scoped by token policy.

This module is meant to be imported qualified. For example: 

>>> import qualified Cardano.Wallet.Primitive.Types.TokenBundle as TB
Synopsis

Types

data TokenBundle Source #

Combines a Coin (lovelace) value with a map of named token quantities, grouped by token policy.

Constructors

TokenBundle

Fields

Instances

Instances details
Eq TokenBundle Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

(==) :: TokenBundle -> TokenBundle -> Bool Source #

(/=) :: TokenBundle -> TokenBundle -> Bool Source #

( TypeError (' Text "Ord not supported for token bundles") :: Constraint ) => Ord TokenBundle Source #

Token bundles can be partially ordered, but there is no total ordering of token bundles that's consistent with their arithmetic properties.

In the event that someone attempts to define an Ord instance for the TokenBundle type, we generate a type error.

If some arbitrary ordering is needed (for example, so that token bundles can be included in an ordered set), the recommended course of action is to define a newtype with its own dedicated Ord instance.

Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

compare :: TokenBundle -> TokenBundle -> Ordering Source #

(<) :: TokenBundle -> TokenBundle -> Bool Source #

(<=) :: TokenBundle -> TokenBundle -> Bool Source #

(>) :: TokenBundle -> TokenBundle -> Bool Source #

(>=) :: TokenBundle -> TokenBundle -> Bool Source #

max :: TokenBundle -> TokenBundle -> TokenBundle Source #

min :: TokenBundle -> TokenBundle -> TokenBundle Source #

Read TokenBundle Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

readsPrec :: Int -> ReadS TokenBundle Source #

readList :: ReadS [ TokenBundle ] Source #

readPrec :: ReadPrec TokenBundle Source #

readListPrec :: ReadPrec [ TokenBundle ] Source #

Show TokenBundle Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

showsPrec :: Int -> TokenBundle -> ShowS Source #

show :: TokenBundle -> String Source #

showList :: [ TokenBundle ] -> ShowS Source #

Generic TokenBundle Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Associated Types

type Rep TokenBundle :: Type -> Type Source #

Methods

from :: TokenBundle -> Rep TokenBundle x Source #

to :: Rep TokenBundle x -> TokenBundle Source #

Semigroup TokenBundle Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

(<>) :: TokenBundle -> TokenBundle -> TokenBundle Source #

sconcat :: NonEmpty TokenBundle -> TokenBundle Source #

stimes :: Integral b => b -> TokenBundle -> TokenBundle Source #

Monoid TokenBundle Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

mempty :: TokenBundle Source #

mappend :: TokenBundle -> TokenBundle -> TokenBundle Source #

mconcat :: [ TokenBundle ] -> TokenBundle Source #

NFData TokenBundle Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

rnf :: TokenBundle -> () Source #

Hashable TokenBundle Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

hashWithSalt :: Int -> TokenBundle -> Int Source #

hash :: TokenBundle -> Int Source #

PartialOrd TokenBundle Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

leq :: TokenBundle -> TokenBundle -> Bool Source #

comparable :: TokenBundle -> TokenBundle -> Bool Source #

Ord ( Lexicographic TokenBundle ) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

compare :: Lexicographic TokenBundle -> Lexicographic TokenBundle -> Ordering Source #

(<) :: Lexicographic TokenBundle -> Lexicographic TokenBundle -> Bool Source #

(<=) :: Lexicographic TokenBundle -> Lexicographic TokenBundle -> Bool Source #

(>) :: Lexicographic TokenBundle -> Lexicographic TokenBundle -> Bool Source #

(>=) :: Lexicographic TokenBundle -> Lexicographic TokenBundle -> Bool Source #

max :: Lexicographic TokenBundle -> Lexicographic TokenBundle -> Lexicographic TokenBundle Source #

min :: Lexicographic TokenBundle -> Lexicographic TokenBundle -> Lexicographic TokenBundle Source #

ToJSON ( ApiT TokenBundle ) Source #
Instance details

Defined in Cardano.Wallet.Api.Types

Methods

toJSON :: ApiT TokenBundle -> Value Source #

toEncoding :: ApiT TokenBundle -> Encoding Source #

toJSONList :: [ ApiT TokenBundle ] -> Value Source #

toEncodingList :: [ ApiT TokenBundle ] -> Encoding Source #

FromJSON ( ApiT TokenBundle ) Source #
Instance details

Defined in Cardano.Wallet.Api.Types

Methods

parseJSON :: Value -> Parser ( ApiT TokenBundle ) Source #

parseJSONList :: Value -> Parser [ ApiT TokenBundle ] Source #

Buildable ( Nested TokenBundle ) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

build :: Nested TokenBundle -> Builder Source #

Buildable ( Flat TokenBundle ) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

build :: Flat TokenBundle -> Builder Source #

Buildable ( SelectionOf TokenBundle ) Source #
Instance details

Defined in Cardano.Wallet.CoinSelection

Methods

build :: SelectionOf TokenBundle -> Builder Source #

Buildable ( WalletUTxO , TokenBundle ) Source #
Instance details

Defined in Cardano.Wallet.CoinSelection

Methods

build :: ( WalletUTxO , TokenBundle ) -> Builder Source #

type Rep TokenBundle Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

type Rep TokenBundle = D1 (' MetaData "TokenBundle" "Cardano.Wallet.Primitive.Types.TokenBundle" "cardano-wallet-core-2022.7.1-AGKhlyz9liLKN3QqZD1gj" ' False ) ( C1 (' MetaCons "TokenBundle" ' PrefixI ' True ) ( S1 (' MetaSel (' Just "coin") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 Coin ) :*: S1 (' MetaSel (' Just "tokens") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 TokenMap )))

data AssetId Source #

A combination of a token policy identifier and a token name that can be used as a compound identifier.

Constructors

AssetId

Fields

Instances

Instances details
Eq AssetId Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

(==) :: AssetId -> AssetId -> Bool Source #

(/=) :: AssetId -> AssetId -> Bool Source #

Ord AssetId Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

compare :: AssetId -> AssetId -> Ordering Source #

(<) :: AssetId -> AssetId -> Bool Source #

(<=) :: AssetId -> AssetId -> Bool Source #

(>) :: AssetId -> AssetId -> Bool Source #

(>=) :: AssetId -> AssetId -> Bool Source #

max :: AssetId -> AssetId -> AssetId Source #

min :: AssetId -> AssetId -> AssetId Source #

Read AssetId Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

readsPrec :: Int -> ReadS AssetId Source #

readList :: ReadS [ AssetId ] Source #

readPrec :: ReadPrec AssetId Source #

readListPrec :: ReadPrec [ AssetId ] Source #

Show AssetId Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

showsPrec :: Int -> AssetId -> ShowS Source #

show :: AssetId -> String Source #

showList :: [ AssetId ] -> ShowS Source #

Generic AssetId Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Associated Types

type Rep AssetId :: Type -> Type Source #

Methods

from :: AssetId -> Rep AssetId x Source #

to :: Rep AssetId x -> AssetId Source #

NFData AssetId Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

rnf :: AssetId -> () Source #

type Rep AssetId Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

type Rep AssetId = D1 (' MetaData "AssetId" "Cardano.Wallet.Primitive.Types.TokenMap" "cardano-wallet-core-2022.7.1-AGKhlyz9liLKN3QqZD1gj" ' False ) ( C1 (' MetaCons "AssetId" ' PrefixI ' True ) ( S1 (' MetaSel (' Just "tokenPolicyId") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 TokenPolicyId ) :*: S1 (' MetaSel (' Just "tokenName") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 TokenName )))

Construction

empty :: TokenBundle Source #

The empty token bundle.

fromFlatList :: Coin -> [( AssetId , TokenQuantity )] -> TokenBundle Source #

Creates a token bundle from a coin and a flat list of token quantities.

If a token name appears more than once in the list under the same policy, its associated quantities will be added together in the resultant bundle.

fromNestedList :: Coin -> [( TokenPolicyId , NonEmpty ( TokenName , TokenQuantity ))] -> TokenBundle Source #

Creates a token bundle from a coin and a nested list of token quantities.

If a token name appears more than once in the list under the same policy, its associated quantities will be added together in the resultant bundle.

fromNestedMap :: ( Coin , Map TokenPolicyId ( NonEmptyMap TokenName TokenQuantity )) -> TokenBundle Source #

fromTokenMap :: TokenMap -> TokenBundle Source #

Deconstruction

toFlatList :: TokenBundle -> ( Coin , [( AssetId , TokenQuantity )]) Source #

Converts a token bundle to a coin and a flat list of token quantities.

Coins

fromCoin :: Coin -> TokenBundle Source #

Creates a singleton token bundle from an ada Coin value.

toCoin :: TokenBundle -> Maybe Coin Source #

Coerces a token bundle to an ada Coin value.

Returns a coin if (and only if) the token bundle has no other tokens.

isCoin :: TokenBundle -> Bool Source #

Indicates True if (and only if) a token bundle has no tokens other than an ada Coin value.

getCoin :: TokenBundle -> Coin Source #

Gets the current ada Coin value from a token bundle.

If you need to assert that a bundle has no other tokens, consider using the toCoin function instead.

setCoin :: TokenBundle -> Coin -> TokenBundle Source #

Sets the current ada Coin value for a token bundle.

Arithmetic

add :: TokenBundle -> TokenBundle -> TokenBundle Source #

Adds one token bundle to another.

subtract :: TokenBundle -> TokenBundle -> Maybe TokenBundle Source #

Subtracts the second token bundle from the first.

Returns Nothing if the second bundle is not less than or equal to the first bundle when compared with the leq function.

difference :: TokenBundle -> TokenBundle -> TokenBundle Source #

Analogous to Set.difference , return the difference between two token maps.

The following property holds: prop> x leq (x difference y) add y

Note that there's a leq rather than equality, which we'd expect if this was subtraction of integers. I.e. 

>>> (0 - 1) + 1
0

whereas 

>>> let oneToken = fromFlatList coin [(aid, TokenQuantity 1)]
>>> (mempty `difference` oneToken) `add` oneToken
oneToken

Quantities

getQuantity :: TokenBundle -> AssetId -> TokenQuantity Source #

Gets the quantity associated with a given asset.

If the given bundle does not have an entry for the specified asset, this function returns a value of zero.

hasQuantity :: TokenBundle -> AssetId -> Bool Source #

Returns true if and only if the given bundle has a non-zero quantity for the given asset.

setQuantity :: TokenBundle -> AssetId -> TokenQuantity -> TokenBundle Source #

Sets the quantity associated with a given asset.

If the given quantity is zero, the resultant bundle will not have an entry for the given asset.

Partitioning

equipartitionAssets Source #

Arguments

:: TokenBundle

The token bundle to be partitioned.

-> NonEmpty a

Represents the number of portions in which to partition the bundle.

-> NonEmpty TokenBundle

The partitioned bundles.

Partitions a token bundle into n smaller bundles, where the asset sets of the resultant bundles are disjoint.

In the resultant bundles, the smallest asset set size and largest asset set size will differ by no more than 1.

The ada Coin quantity is equipartitioned across the resulting bundles.

The quantities of each non-ada asset are unchanged.

equipartitionQuantitiesWithUpperBound Source #

Arguments

:: TokenBundle
-> TokenQuantity

Maximum allowable token quantity.

-> NonEmpty TokenBundle

The partitioned bundles.

Partitions a token bundle into n smaller bundles, where the quantity of each token is equipartitioned across the resultant bundles, with the goal that no token quantity in any of the resultant bundles exceeds the given upper bound.

The value n is computed automatically, and is the minimum value required to achieve the goal that no token quantity in any of the resulting bundles exceeds the maximum allowable token quantity.

Ordering

newtype Lexicographic a Source #

Defines a lexicographic ordering.

Constructors

Lexicographic

Fields

Instances

Instances details
Eq a => Eq ( Lexicographic a) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

(==) :: Lexicographic a -> Lexicographic a -> Bool Source #

(/=) :: Lexicographic a -> Lexicographic a -> Bool Source #

Ord ( Lexicographic TokenMap ) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

compare :: Lexicographic TokenMap -> Lexicographic TokenMap -> Ordering Source #

(<) :: Lexicographic TokenMap -> Lexicographic TokenMap -> Bool Source #

(<=) :: Lexicographic TokenMap -> Lexicographic TokenMap -> Bool Source #

(>) :: Lexicographic TokenMap -> Lexicographic TokenMap -> Bool Source #

(>=) :: Lexicographic TokenMap -> Lexicographic TokenMap -> Bool Source #

max :: Lexicographic TokenMap -> Lexicographic TokenMap -> Lexicographic TokenMap Source #

min :: Lexicographic TokenMap -> Lexicographic TokenMap -> Lexicographic TokenMap Source #

Ord ( Lexicographic TokenBundle ) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

compare :: Lexicographic TokenBundle -> Lexicographic TokenBundle -> Ordering Source #

(<) :: Lexicographic TokenBundle -> Lexicographic TokenBundle -> Bool Source #

(<=) :: Lexicographic TokenBundle -> Lexicographic TokenBundle -> Bool Source #

(>) :: Lexicographic TokenBundle -> Lexicographic TokenBundle -> Bool Source #

(>=) :: Lexicographic TokenBundle -> Lexicographic TokenBundle -> Bool Source #

max :: Lexicographic TokenBundle -> Lexicographic TokenBundle -> Lexicographic TokenBundle Source #

min :: Lexicographic TokenBundle -> Lexicographic TokenBundle -> Lexicographic TokenBundle Source #

Show a => Show ( Lexicographic a) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

showsPrec :: Int -> Lexicographic a -> ShowS Source #

show :: Lexicographic a -> String Source #

showList :: [ Lexicographic a] -> ShowS Source #

Serialization

newtype Flat a Source #

When used with the Buildable or ToJSON instances, provides a flat serialization style, where token quantities are paired with their asset identifiers.

Constructors

Flat

Fields

Instances

Instances details
Eq a => Eq ( Flat a) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

(==) :: Flat a -> Flat a -> Bool Source #

(/=) :: Flat a -> Flat a -> Bool Source #

Ord a => Ord ( Flat a) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

compare :: Flat a -> Flat a -> Ordering Source #

(<) :: Flat a -> Flat a -> Bool Source #

(<=) :: Flat a -> Flat a -> Bool Source #

(>) :: Flat a -> Flat a -> Bool Source #

(>=) :: Flat a -> Flat a -> Bool Source #

max :: Flat a -> Flat a -> Flat a Source #

min :: Flat a -> Flat a -> Flat a Source #

Show a => Show ( Flat a) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

showsPrec :: Int -> Flat a -> ShowS Source #

show :: Flat a -> String Source #

showList :: [ Flat a] -> ShowS Source #

Generic ( Flat a) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Associated Types

type Rep ( Flat a) :: Type -> Type Source #

Methods

from :: Flat a -> Rep ( Flat a) x Source #

to :: Rep ( Flat a) x -> Flat a Source #

ToJSON ( Flat TokenMap ) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

toJSON :: Flat TokenMap -> Value Source #

toEncoding :: Flat TokenMap -> Encoding Source #

toJSONList :: [ Flat TokenMap ] -> Value Source #

toEncodingList :: [ Flat TokenMap ] -> Encoding Source #

FromJSON ( Flat TokenMap ) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

parseJSON :: Value -> Parser ( Flat TokenMap ) Source #

parseJSONList :: Value -> Parser [ Flat TokenMap ] Source #

Buildable ( Flat TokenMap ) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

build :: Flat TokenMap -> Builder Source #

Buildable ( Flat TokenBundle ) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

build :: Flat TokenBundle -> Builder Source #

type Rep ( Flat a) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

type Rep ( Flat a) = D1 (' MetaData "Flat" "Cardano.Wallet.Primitive.Types.TokenMap" "cardano-wallet-core-2022.7.1-AGKhlyz9liLKN3QqZD1gj" ' True ) ( C1 (' MetaCons "Flat" ' PrefixI ' True ) ( S1 (' MetaSel (' Just "getFlat") ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 a)))

newtype Nested a Source #

When used with the Buildable or ToJSON instances, provides a nested serialization style, where token quantities are grouped by policy identifier.

Constructors

Nested

Fields

Instances

Instances details
Eq a => Eq ( Nested a) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

(==) :: Nested a -> Nested a -> Bool Source #

(/=) :: Nested a -> Nested a -> Bool Source #

Ord a => Ord ( Nested a) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

compare :: Nested a -> Nested a -> Ordering Source #

(<) :: Nested a -> Nested a -> Bool Source #

(<=) :: Nested a -> Nested a -> Bool Source #

(>) :: Nested a -> Nested a -> Bool Source #

(>=) :: Nested a -> Nested a -> Bool Source #

max :: Nested a -> Nested a -> Nested a Source #

min :: Nested a -> Nested a -> Nested a Source #

Show a => Show ( Nested a) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

showsPrec :: Int -> Nested a -> ShowS Source #

show :: Nested a -> String Source #

showList :: [ Nested a] -> ShowS Source #

Generic ( Nested a) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Associated Types

type Rep ( Nested a) :: Type -> Type Source #

Methods

from :: Nested a -> Rep ( Nested a) x Source #

to :: Rep ( Nested a) x -> Nested a Source #

ToJSON ( Nested TokenMap ) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

toJSON :: Nested TokenMap -> Value Source #

toEncoding :: Nested TokenMap -> Encoding Source #

toJSONList :: [ Nested TokenMap ] -> Value Source #

toEncodingList :: [ Nested TokenMap ] -> Encoding Source #

FromJSON ( Nested TokenMap ) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

parseJSON :: Value -> Parser ( Nested TokenMap ) Source #

parseJSONList :: Value -> Parser [ Nested TokenMap ] Source #

Buildable ( Nested TokenMap ) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

Methods

build :: Nested TokenMap -> Builder Source #

Buildable ( Nested TokenBundle ) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenBundle

Methods

build :: Nested TokenBundle -> Builder Source #

type Rep ( Nested a) Source #
Instance details

Defined in Cardano.Wallet.Primitive.Types.TokenMap

type Rep ( Nested a) = D1 (' MetaData "Nested" "Cardano.Wallet.Primitive.Types.TokenMap" "cardano-wallet-core-2022.7.1-AGKhlyz9liLKN3QqZD1gj" ' True ) ( C1 (' MetaCons "Nested" ' PrefixI ' True ) ( S1 (' MetaSel (' Just "getNested") ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 a)))

Queries

getAssets :: TokenBundle -> Set AssetId Source #

Transformations

mapAssetIds :: ( AssetId -> AssetId ) -> TokenBundle -> TokenBundle Source #

Unsafe operations

unsafeSubtract :: TokenBundle -> TokenBundle -> TokenBundle Source #

Subtracts the second token bundle from the first.

Pre-condition: the second bundle is less than or equal to the first bundle when compared with the leq function.

Throws a run-time exception if the pre-condition is violated.