Plutus.V1.Ledger.Value

• 1. 📜 Overview

• 2. 🔧 LANGUAGE PRAGMAS AND IMPORTS

• 3. 🗄️ Core Types

  • 3.1 💱 CurrencySymbol

  • 3.2 🏷️ TokenName

  • 3.3 🔖 AssetClass

  • 3.4 💰 Value

• 4. ⚙️ Key Functions

  • 4.1 🪙 currencySymbol / mpsSymbol / currencyMPSHash

  • 4.2 🇦 adaSymbol / adaToken

  • 4.3 🎨 assetClass / assetClassValue / assetClassValueOf

  • 4.4 🔢 valueOf / symbols / singleton

  • 4.5 📚 unionWith / flattenValue

  • 4.6 ⚖️ geq / gt / leq / lt

  • 4.7 🚫 isZero / split

• 5. 🏭 On-Chain Derivations

• 6. 📚 Glossary

---

1 📜 Overview

The Plutus.V1.Ledger.Value module handles multi-currency amounts in Plutus:

• CurrencySymbol and TokenName for identifying tokens.

• AssetClass as a pair of symbol and name.

• Value as a nested map from symbols to token names to integer quantities.

• Utilities for constructing, querying, combining, and comparing Values.

---

2 🔧 LANGUAGE PRAGMAS AND IMPORTS

{-# LANGUAGE DeriveAnyClass      #-}
{-# LANGUAGE DeriveGeneric       #-}
{-# LANGUAGE DerivingVia         #-}
{-# LANGUAGE FlexibleContexts    #-}
{-# LANGUAGE FlexibleInstances   #-}
{-# LANGUAGE LambdaCase         #-}
{-# LANGUAGE NoImplicitPrelude   #-}
{-# LANGUAGE OverloadedLists    #-}
{-# LANGUAGE OverloadedStrings  #-}
{-# LANGUAGE TemplateHaskell     #-}
{-# OPTIONS_GHC -Wno-orphans        #-}
{-# OPTIONS_GHC -fno-omit-interface-pragmas #-}
{-# OPTIONS_GHC -fno-spec-constr    #-}
{-# OPTIONS_GHC -fno-specialise    #-}

import Prelude qualified as Haskell
import Control.DeepSeq (NFData)
import Data.String     (IsString)
import Data.Text       (Text)
import Data.Text.Encoding qualified as E
import Data.ByteString qualified as BS
import Data.Data (Data)
import GHC.Generics (Generic)
import PlutusTx qualified
import PlutusTx.AssocMap qualified as Map
import PlutusTx.Lift (makeLift)
import PlutusTx.Prelude hiding (sort)
import PlutusTx.These
import Prettyprinter
import Prettyprinter.Extras (PrettyShow(..))
import Plutus.V1.Ledger.Bytes (LedgerBytes(..), encodeByteString)
import Plutus.V1.Ledger.Scripts (MintingPolicyHash(..))

---

3 🗄️ Core Types

3.1 💱 CurrencySymbol

newtype CurrencySymbol = CurrencySymbol { unCurrencySymbol :: PlutusTx.BuiltinByteString }
  deriving (Eq, Ord, ToData, FromData, UnsafeFromData)
  deriving (Show, Pretty, IsString) via LedgerBytes
  deriving Generic, Data, NFData

• Identifies a monetary policy by its hash.

3.2 🏷️ TokenName

newtype TokenName = TokenName { unTokenName :: PlutusTx.BuiltinByteString }
  deriving (Eq, Ord, ToData, FromData, UnsafeFromData)
  deriving Generic, Data, NFData
  deriving Pretty via PrettyShow TokenName
instance IsString TokenName where fromString = ...

• Names tokens under a policy, with pretty-printing of UTF-8 or hex.

3.3 🔖 AssetClass

newtype AssetClass = AssetClass { unAssetClass :: (CurrencySymbol, TokenName) }
  deriving (Eq, Ord, ToData, FromData, UnsafeFromData)
  deriving Pretty via PrettyShow (CurrencySymbol, TokenName)
  deriving Generic, Data, NFData

• Pairs symbol and name to define a specific asset.

3.4 💰 Value

newtype Value = Value { getValue :: Map.Map CurrencySymbol (Map.Map TokenName Integer) }
  deriving (ToData, FromData, UnsafeFromData)
  deriving Pretty via PrettyShow Value
  deriving Generic, Data, NFData

• Represents quantities of many assets; operations are pointwise by symbol and token.

---

4 ⚙️ Key Functions

4.1 🪙 currencySymbol / mpsSymbol / currencyMPSHash

currencySymbol :: BS.ByteString -> CurrencySymbol
mpsSymbol :: MintingPolicyHash -> CurrencySymbol
currencyMPSHash :: CurrencySymbol -> MintingPolicyHash

• Construct and invert mappings between policy hashes and symbols.

4.2 🇦 adaSymbol / adaToken

adaSymbol :: CurrencySymbol
adaToken  :: TokenName

• Reserved empty-byte representations for the built-in ADA currency.

4.3 🎨 assetClass / assetClassValue / assetClassValueOf

assetClass :: CurrencySymbol -> TokenName -> AssetClass
assetClassValue :: AssetClass -> Integer -> Value
assetClassValueOf :: Value -> AssetClass -> Integer

• Create an AssetClass, wrap it into a Value, and query its quantity.

4.4 🔢 valueOf / symbols / singleton

valueOf :: Value -> CurrencySymbol -> TokenName -> Integer
symbols :: Value -> [CurrencySymbol]
singleton :: CurrencySymbol -> TokenName -> Integer -> Value

• Query elementwise quantities, list all symbols, or build a one-asset Value.

4.5 📚 unionWith / flattenValue

unionWith :: (Integer -> Integer -> Integer) -> Value -> Value -> Value
flattenValue :: Value -> [(CurrencySymbol, TokenName, Integer)]

• Merge two Values with a combining function, or flatten to a list of non-zero entries.

4.6 ⚖️ geq / gt / leq / lt

geq, gt, leq, lt :: Value -> Value -> Bool

• Partial-order comparisons on Value where missing entries count as zero.

4.7 🚫 isZero / split

isZero :: Value -> Bool
split  :: Value -> (Value, Value)

• Check for emptiness, or decompose into negative and positive parts.

---

5 🏭 On-Chain Derivations

makeLift ''CurrencySymbol
makeLift ''TokenName
makeLift ''AssetClass
makeLift ''Value

• makeLift generates Lift instances for embedding these types in on-chain code.

---

6 📚 Glossary

• CurrencySymbol: hash identifying a monetary policy.

• TokenName: UTF-8 or hex-encoded label for a token.

• AssetClass: a pair (symbol, name) uniquely identifying an asset.

• Value: map from currencies to token quantities.

• unionWith: pointwise merge of two Values.

• split: separate deficits vs surpluses in a Value.

• Partial order: comparisons where missing entries are treated as zero.

• Flatten: list non-zero entries for inspection.

• ADA: the built-in Cardano currency, represented by empty symbol and token.