Generated with

docs/scalus/scalus.ledger/scalus.ledger.api/scalus.ledger.api.v1/Value

Value

scalus.ledger.api.v1.Value

See theValue companion class

object Value

Attributes

Companion: class
Graph
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: Value.type

Members list

Type members

Inherited and Abstract types

The names of the product elements

Attributes

Inherited from:: Mirror

The name of the type

Attributes

Inherited from:: Mirror

Value members

Concrete methods

Creates a Value containing the specified amount of a specific policy id and token. If the amount is zero, it returns Value.zero.

Value parameters

cs: The policy id
tn: The token name
v: The amount of the token

Attributes

Returns

A new Value containing the specified amount of the token, or Value.zero if the amount is zero

Example

 Value(Value.adaPolicyId, Value.adaTokenName, BigInt(1000000)) === Value.lovelace(BigInt(1000000))
 val policyId: PolicyId = ByteString.fromString("policyId")
 val tokenName: TokenName = ByteString.fromString("tokenName")
 val value = Value(policyId, tokenName, BigInt(100))
 value.quantityOf(policyId, tokenName) === BigInt(100)
 value.getLovelace === BigInt(0)
 value.isZero === false
 Value(policyId, tokenName, BigInt(0)) === Value.zero

Converts a Value to a debug string representation.

Formats the Value as a string showing policy IDs and token amounts in a human-readable format. Each policy ID and its associated tokens are displayed with their hex representations and amounts.

Value parameters

v: The Value to convert to string

Attributes

Returns

A formatted string representation of the Value

Example

 val value = Value.fromList(
   List.Cons(
     (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(1000000)), List.Nil)),
     List.Cons(
       (ByteString.fromString("ff"), List.Cons((ByteString.fromString("TOKEN"), BigInt(100)), List.Nil)),
       List.Nil
     )
   )
 )
 // Prints: { policy# -> { #: 1000000 }, policy#6666 -> { #544f4b454e: 100 } }
 println(Value.debugToString(value))

Tests if two Value instances are equal.

Compares two Value instances by checking if they contain the same policy ids and tokens with equal amounts, treating absent tokens as having zero amount.

Value parameters

a: First Value instance
b: Second Value instance

Attributes

Returns

true if both Value instances are equal, false otherwise

Example

 val value1 = Value.lovelace(BigInt(1000000))
 val value2 = Value.lovelace(BigInt(1000000))
 Value.eq(value1, value2) === true
 val value3 = Value.lovelace(BigInt(500000))
 Value.eq(value1, value3) === false

Tests if two token asset maps contain exactly the same tokens with equal amounts.

Compares two maps of token names to amounts, treating absent tokens as having zero amount. The comparison checks if each token has equal amounts in both maps.

Value parameters

a: First map of token names to amounts
b: Second map of token names to amounts

Attributes

Returns

true if both maps contain the same tokens with equal amounts, false otherwise

Example

 val assets1 = SortedMap.fromList(
   List.Cons(
     (ByteString.fromString("TOKEN1"), BigInt(100)),
     List.Cons(
       (ByteString.fromString("TOKEN2"), BigInt(200)),
       List.Nil
     )
   )
 )
 val assets2 = SortedMap.fromList(
   List.Cons(
     (ByteString.fromString("TOKEN1"), BigInt(100)),
     List.Cons(
       (ByteString.fromString("TOKEN2"), BigInt(200)),
       List.Nil
     )
   )
 )
 Value.equalsAssets(assets1, assets2) === true

Creates a Value from a list of policy ids paired with their token amounts, filtering out zero amounts.

This method safely constructs a Value by:

Removing all tokens with zero amounts
Removing policy ids that have no remaining tokens after filtering

Value parameters

list: A list of tuples containing policy ids and their associated token amounts

Attributes

Returns

A Value with zero amounts filtered out

See also

unsafeFromList for an unfiltered unsafe version or fromStrictlyAscendingListWithNonZeroAmounts for a faster stricter version

Example

 val tokens = List.Cons(
   (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(1000000)), List.Nil)),
   Cons(
     (ByteString.fromString("ff"), List.Cons((ByteString.fromString("TOKEN"), BigInt(0)), List.Nil)),
     List.Nil
   )
 )
 // The second entry will be filtered out due to zero amount
 Value.fromList(tokens) === Value.lovelace(BigInt(1000000))

Creates a Value from a strictly ascending list of policy ids and token amounts, requiring non-zero amounts.

This method enforces stricter requirements than fromList:

The input list must be strictly ascending by policy id
Each token list must be strictly ascending by token name
All token amounts must be non-zero
Token lists cannot be empty

Value parameters

list: A strictly ascending list of tuples containing policy ids and their associated token amounts

Attributes

Returns

A Value constructed from the strictly ascending lists

Throws

scalus.cardano.onchain.RequirementError

If any token amount is zero or any token list is empty

See also

unsafeFromList for an unsafe fast version or fromList for a more permissive slow version that filters invalid entries

Example

 // Successful case - ascending order and non-zero amounts
 val validTokens = List.Cons(
   (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(1000000)), List.Nil)),
   Cons(
     (ByteString.fromString("ff"), List.Cons((ByteString.fromString("TOKEN"), BigInt(100)), List.Nil)),
     List.Nil
   )
 )
 Value.fromStrictlyAscendingListWithNonZeroAmounts(validTokens) // Succeeds
 // Error case - contains zero amount
 val invalidTokens = List.Cons(
   (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(0)), List.Nil)),
   List.Nil
 )
 Value.fromStrictlyAscendingListWithNonZeroAmounts(invalidTokens) // Throws RequirementError

Creates a Value representing a specific amount of ADA in lovelace.

This is a convenience method for creating a Value with the ADA policy id and token name, where the amount is specified in lovelace (1 ADA = 1,000,000 lovelace).

Value parameters

v: The amount of Lovelace

Attributes

Returns

A new Value containing only the specified amount of Lovelace

Example

 Value.lovelace(BigInt(1000000)) === Value(Value.adaPolicyId, Value.adaTokenName, BigInt(1000000))
 Value.lovelace(BigInt(1000000)).getLovelace === BigInt(1000000)
 Value.lovelace(BigInt(1000000)).quantityOf(ByteString.fromString("policyId"), ByteString.fromString("tokenName")) === BigInt(0)
 Value.lovelace(BigInt(0)) === Value.zero

Subtracts the second Value from the first, effectively performing element-wise subtraction of token amounts.

This method subtracts the token amounts in the second Value from those in the first, treating absent tokens as having zero amount.

Value parameters

a: The Value to subtract from
b: The Value to subtract

Attributes

Returns

A new Value containing the result of the subtraction

Example

 val value1 = Value.lovelace(BigInt(1000000))
 val value2 = Value.lovelace(BigInt(500000))
 Value.minus(value1, value2) === Value.lovelace(BigInt(500000))

Multiplies all token amounts in a Value by a specified factor.

This method scales each token amount in the Value by the given factor, effectively multiplying all amounts by the same integer.

Value parameters

factor: The factor to multiply each token amount by
v: The Value to multiply

Attributes

Returns

A new Value with all token amounts multiplied by the factor, or Value.zero if the factor is zero

Example

 val value = Value.fromList(
   List.Cons(
     (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(1000000)), List.Nil)),
     List.Cons(
       (ByteString.fromString("ff"), List.Cons((ByteString.fromString("TOKEN"), BigInt(100)), List.Nil)),
       List.Nil
     )
   )
 )
 Value.multiply(value, BigInt(2)) === Value.fromList(
   List.Cons(
     (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(2000000)), List.Nil)),
     List.Cons(
       (ByteString.fromString("ff"), List.Cons((ByteString.fromString("TOKEN"), BigInt(200)), List.Nil)),
       List.Nil
     )
   )
 )
 Value.multiply(value, BigInt(0)) === Value.zero

Negates all token amounts in a Value, effectively creating the additive inverse.

This method traverses the Value and negates each token amount by subtracting it from zero.

Value parameters

v: The Value to negate

Attributes

Returns

A new Value with all token amounts negated

Example

 val value1 = Value.fromList(
   List.Cons(
     (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(1000000)), List.Nil)),
     List.Cons(
       (ByteString.fromString("ff"), List.Cons((ByteString.fromString("TOKEN"), BigInt(100)), List.Nil)),
       List.Nil
     )
   )
 )
 val value2 = Value.fromList(
   List.Cons(
     (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(-1000000)), List.Nil)),
     List.Cons(
       (ByteString.fromString("ff"), List.Cons((ByteString.fromString("TOKEN"), BigInt(-100)), List.Nil)),
       List.Nil
     )
   )
 )
 Value.negate(value1) === value2

Tests if two Value instances are not equal.

Compares two Value instances by checking if they contain different policy ids or tokens with unequal amounts, treating absent tokens as having zero amount.

Value parameters

a: First Value instance
b: Second Value instance

Attributes

Returns

true if the Value instances are not equal, false otherwise

Example

 val value1 = Value.lovelace(BigInt(1000000))
 val value2 = Value.lovelace(BigInt(1000000))
 Value.nonEq(value1, value2) === false
 val value3 = Value.lovelace(BigInt(500000))
 Value.nonEq(value1, value3) === true

Adds two Value instances together, combining their token amounts.

This method performs an element-wise addition of the token amounts in both Value instances, treating absent tokens as having zero amount.

Value parameters

a: First Value instance
b: Second Value instance

Attributes

Returns

A new Value containing the combined token amounts

Example

 val value1 = Value.lovelace(BigInt(1000000))
 val value2 = Value.lovelace(BigInt(500000))
 Value.plus(value1, value2) === Value.lovelace(BigInt(1500000))

Creates a Value from a list of policy ids paired with their token amounts, without validation.

This method directly constructs a Value from the input list without checking for zero amounts or empty token lists. Use with caution as it may create invalid states.

Value parameters

list: A list of tuples containing policy ids and their associated token amounts

Attributes

Returns

A Value constructed directly from the input list

See also

fromList or fromStrictlyAscendingListWithNonZeroAmounts for safe versions

Example

 val tokens = List.Cons(
   (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(1000000)), List.Nil)),
   Cons(
     (ByteString.fromString("ff"), List.Cons((ByteString.fromString("TOKEN"), BigInt(100)), List.Nil)),
     List.Nil
   )
 )
 Value.unsafeFromList(tokens)

Implementation of the prelude.FromData type class for Value with validation. Validates that:

All token amounts are non-zero
No currency symbol has an empty token list

This method ensures that the Value is well-formed and meets the expected structure.

Attributes

Example

 val data: Data = ... // Some Data representation of a Value
 val value = Value.valueFromDataWithValidation(data) // Converts from Data to Value with validation

Concrete fields

The policy id for ADA, represented as an empty ByteString.

Attributes

Example

 Value.adaPolicyId === ByteString.empty

The token name for ADA, represented as an empty ByteString.

Attributes

Example

 Value.adaTokenName === ByteString.empty

Implementation of the prelude.Ord type class for Value. Only makes sense as a key for collections.

Provides total ordering for Value instances by comparing their underlying sorted maps. The ordering is determined by:

First comparing policy ids
For equal policy ids, comparing their token maps
For equal token names, comparing their amounts

Attributes

Example

val value1 = Value.lovelace(BigInt(1000000))
val value2 = Value.lovelace(BigInt(500000))
value1 <=> value2 // Returns Order.Greater

A value representing zero units of any policy id or token.

Attributes

Example

 Value.zero.isZero === true
 Value.zero.quantityOf(ByteString.fromString("policyId"), ByteString.fromString("tokenName")) === BigInt(0)
 Value.zero.getLovelace === BigInt(0)

Deprecated fields

Attributes

Deprecated: [Since version 0.12.0] Use adaPolicyId instead
Use adaPolicyId instead.

Givens

Implementation of the prelude.Eq type class for Value.

Provides equality comparison between two Value instances by delegating to Value.eq. Two Value instances are considered equal if they contain exactly the same policy ids and tokens with equal amounts.

Attributes

Example

 val value1 = Value.fromList(
   List.Cons(
     (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(1000000)), List.Nil)),
     List.Nil
   )
 )
 val value2 = Value.fromList(
   List.Cons(
     (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(1000000)), List.Nil)),
     List.Nil
   )
 )
 value1 === value2 // true, using derived Eq instance

Implementation of the prelude.FromData type class for Value.

Converts a Data representation back into a Value. This method assumes that the input data is well-formed and does not perform any validation on the token amounts or structure.

Attributes

Example

 val data: Data = ... // Some Data representation of a Value
 val value = Value.fromData(data) // Converts from Data to Value

Implementation of the prelude.ToData type class for Value.

Converts a Value to a Data representation by converting its sorted map structure.

Attributes

Example

 val value = Value.fromList(
   List.Cons(
     (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(1000000)), List.Nil)),
     List.Nil
   )
 )
 val data = value.toData // Converts to Data representation

Extensions

Deprecated extensions

extension (v: Value)

Extension alias for Value.multiply.

Attributes

Extension alias for Value.plus.

Attributes

Extension alias for Value.minus.

Attributes

Deprecated: [Since version 0.12.0] Use policyIds instead
Use policyIds instead.

Flattens the Value into a list of policy id, token name, and amount triples.

Converts the nested map structure into a flat list representation where each element contains the policy id, token name, and corresponding amount.

Attributes

Returns

A flattened list of tuples containing (policyId, tokenName, amount)

Example

 val value = Value.fromList(
   List.Cons(
     (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(1000000)), List.Nil)),
     List.Cons(
       (ByteString.fromString("ff"), List.Cons((ByteString.fromString("TOKEN"), BigInt(100)), List.Nil)),
       List.Nil
     )
   )
 )
 value.flatten ===
 List.Cons(
    (Value.adaPolicyId, Value.adaTokenName, BigInt(1000000)),
    List.Cons(
      (ByteString.fromString("ff"), ByteString.fromString("TOKEN"), BigInt(100)),
      List.Nil
    )
 )

Returns the amount of Lovelace in this Value.

If the Value contains no Lovelace, it returns zero.

Attributes

Returns

The amount of Lovelace in this Value

Example

 val value = Value.lovelace(BigInt(1000000))
 value.getLovelace === BigInt(1000000)
 val emptyValue = Value.zero
 emptyValue.getLovelace === BigInt(0)

Checks if this Value is non-zero and positive, meaning it contains at least one token or currency symbol with a non-zero positive amount and all amounts are positive.

Attributes

Returns: true if the Value is non-empty and has all positive amounts, false otherwise

Checks if this Value is zero, meaning it contains no tokens or currency symbols.

Attributes

Returns

true if the Value is empty, false otherwise

Example

 val value = Value.zero
 value.isZero === true
 val nonZeroValue = Value.lovelace(BigInt(1000000))
 nonZeroValue.isZero === false

Checks if this Value is non-zero, meaning it contains at least one token or currency symbol with a non-zero amount.

Attributes

Returns

true if the Value is non-empty, false otherwise

Example

 val value = Value.zero
 value.nonZero === false
 val nonZeroValue = Value.lovelace(BigInt(1000000))
 nonZeroValue.nonZero === true

A list of all policy ids in that scalus.ledger.api.v1.Value with non-zero tokens.

Attributes

Returns

A list of sorted scalus.ledger.api.v1.PolicyId

Example

 val value = Value.fromList(
   List.Cons(
     (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(1000000)), List.Nil)),
     List.Cons(
       (ByteString.fromString("ff"), List.Cons((ByteString.fromString("TOKEN"), BigInt(100)), List.Nil)),
       List.Nil
     )
   )
 )
 value.policyIds ===
 List.Cons(
    Value.adaPolicyId,
    List.Cons(
      ByteString.fromString("ff"),
      List.Nil
    )
 )

Gets the amount of a specific token in a policy id from a Value.

Returns the token amount for the given policy id and token name pair. If either the policy id or token name is not found, returns zero.

Value parameters

cs: The policy id to look up
tn: The token name to look up within that policy id

Attributes

Returns

The amount of the specified token, or zero if not found

Example

 val value = Value.fromList(
   List.Cons(
     (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(1000000)), List.Nil)),
     List.Cons(
       (ByteString.fromString("ff"), List.Cons((ByteString.fromString("TOKEN"), BigInt(100)), List.Nil)),
       List.Nil
     )
   )
 )
 value.quantityOf(Value.adaPolicyId, Value.adaTokenName) === BigInt(1000000)
 value.quantityOf(ByteString.fromString("ff"), ByteString.fromString("TOKEN")) === BigInt(100)
 value.quantityOf(ByteString.fromString("missing"), ByteString.fromString("TOKEN")) === BigInt(0)

Extension alias for Value.debugToString.

Attributes

Get all tokens associated with a given policy.

Returns the token SortedMap for the given policy id. If the policy id is not found, returns an empty SortedMap.

Value parameters

cs: The policy id to look up

Attributes

Returns

The SortedMap of the specified token, or an empty SortedMap if not found

Example

 val value = Value.fromList(
   List.Cons(
     (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(1000000)), List.Nil)),
     List.Cons(
       (utf8"ff", List.Cons((utf8"TOKEN", BigInt(100)), List.Nil)),
       List.Nil
     )
   )
 )
 value.quantityOf(Value.adaPolicyId) === SortedMap.singleton(Value.adaTokenName, BigInt(1000000))
 value.quantityOf(utf8"ff") === SortedMap.singleton(utf8"TOKEN", BigInt(100))
 value.quantityOf(utf8"missing") === SortedMap.empty

Extension alias for Value.negate.

Attributes

Returns a new Value with all ADA/Lovelace tokens removed.

This method creates a copy of the value with the ADA policy id removed, effectively removing all Lovelace tokens while preserving other tokens.

Attributes

Returns

A new Value without any Lovelace tokens

Example

 val value = Value.fromList(
   List.Cons(
     (Value.adaPolicyId, List.Cons((Value.adaTokenName, BigInt(1000000)), List.Nil)),
     List.Cons(
       (ByteString.fromString("ff"), List.Cons((ByteString.fromString("TOKEN"), BigInt(100)), List.Nil)),
       List.Nil
     )
   )
 )
 val withoutAda = Value.fromList(
   List.Cons(
     (ByteString.fromString("ff"), List.Cons((ByteString.fromString("TOKEN"), BigInt(100)), List.Nil)),
     List.Nil
   )
 )
 value.withoutLovelace === withoutAda

In this article

Generated with