docs
API
Generated with
docs/scalus/scalus.cardano/scalus.cardano.onchain/scalus.cardano.onchain.plutus/scalus.cardano.onchain.plutus.v1/Value

Value

scalus.cardano.onchain.plutus.v1.Value
See theValue companion object
case class Value

Attributes

Companion
object
Graph
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all

Members list

Value members

Concrete methods

inline def *(factor: BigInt): Value
Extension method from Value

Extension alias for Value.multiply.

Extension alias for Value.multiply.

Attributes

inline def +(other: Value): Value
Extension method from Value

Extension alias for Value.plus.

Extension alias for Value.plus.

Attributes

inline def -(other: Value): Value
Extension method from Value

Extension alias for Value.minus.

Extension alias for Value.minus.

Attributes

def containsAtLeast(other: Value): Boolean
Extension method from Value

Tests whether this Value contains at least the amounts in other.

Tests whether this Value contains at least the amounts in other.

For every (policy id, token name, amount) entry in other, this Value must hold at least that amount. Fails (throws) when either value contains a negative amount - mirroring the CIP-153 valueContains builtin: for values in canonical form the result is identical on every protocol version. For non-canonical values (zero amounts, empty inner maps - only constructible via the unsafe constructors) the PV11 builtin lowering may fail or differ.

At PV11 (vanRossem) this method lowers to the valueContains builtin, which requires both values to be in canonical form (strictly ascending keys, no zero amounts, no empty inner maps, keys at most 32 bytes, amounts within the signed 128-bit range); a non-canonical value makes the script fail. See Options.valueBuiltins.

Attributes

Example 
 val a = Value.lovelace(BigInt(1000))
 val b = Value.lovelace(BigInt(400))
 a.containsAtLeast(b) === true
 b.containsAtLeast(a) === false
def flatten: List[(PolicyId, TokenName, BigInt)]
Extension method from Value

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

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
    )
 )
def getLovelace: BigInt
Extension method from Value

Returns the amount of Lovelace in this Value.

Returns the amount of Lovelace in this Value.

If the Value contains no Lovelace, it returns zero.

At PV11 (vanRossem) with Options.valueBuiltins enabled (the default) this delegates to quantityOf and thus lowers to the CIP-153 lookupCoin builtin, which requires the value in canonical form (strictly ascending keys, no zero amounts, no empty inner maps, keys at most 32 bytes, amounts within the signed 128-bit range) and makes the script fail otherwise. See Options.valueBuiltins.

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)
inline def hasNft(cs: PolicyId, tn: TokenName): Boolean
Extension method from Value

Checks that exactly one unit of the (cs, tn) asset is present. Other assets, under this policy or any other, are tolerated.

Checks that exactly one unit of the (cs, tn) asset is present. Other assets, under this policy or any other, are tolerated.

This is the state-token / beacon check. The strict twin, which also rejects any other token under cs, is hasOnly with amount 1. A quantity compared with > 0 is a different predicate for any asset that is not an NFT; prefer this one for tokens that are minted exactly once.

Value parameters

cs

The policy id

tn

The token name

Attributes

Returns

true if quantityOf(cs, tn) is exactly 1

Example 
 Value(utf8"pid", utf8"BEACON", 1).hasNft(utf8"pid", utf8"BEACON") === true
 Value(utf8"pid", utf8"BEACON", 2).hasNft(utf8"pid", utf8"BEACON") === false
 Value.lovelace(1).hasNft(utf8"pid", utf8"BEACON") === false
def hasOnly(cs: PolicyId, tn: TokenName, amount: BigInt): Boolean
Extension method from Value

Tests whether the tokens under cs are exactly {tn -> amount}.

Tests whether the tokens under cs are exactly {tn -> amount}.

True iff this Value holds amount of tn under cs and NO other token of that policy id. Other policy ids are not constrained, so the check composes with other scripts acting in the same transaction. Negative amounts work too, e.g. hasOnly(cs, tn, -1) checks an exact single-token burn.

This is the recommended way to verify an exact mint, e.g. that a minting policy forges exactly one beacon NFT and nothing else under its own policy id: tx.mint.hasOnly(ownPolicyId, tn, 1). It costs a single equalsData on the policy's token map instead of an element-wise SortedMap comparison.

The equality is on the underlying Data encoding, so it assumes this Value is in canonical form (strictly ascending keys, no zero amounts, no empty inner maps) - true for every ledger-provided value such as tx.mint or an output's value. A non-canonical value (constructible only via the unsafe constructors) may compare unequal to a semantically equal one. In particular amount == 0 returns false on canonical values: they never store zero amounts.

Value parameters

amount

The exact amount required for tn

cs

The policy id whose tokens must be exactly {tn -> amount}

tn

The single token name allowed under cs

Attributes

Example 
 val beacon = Value(utf8"pid", utf8"BEACON", 1)
 beacon.hasOnly(utf8"pid", utf8"BEACON", 1) === true
 beacon.hasOnly(utf8"pid", utf8"BEACON", 2) === false
 beacon.hasOnly(utf8"other", utf8"BEACON", 1) === false
 val two = Value.unsafeFromList(
   List((utf8"pid", List((utf8"BEACON", BigInt(1)), (utf8"BEACON1", BigInt(1)))))
 )
 two.hasOnly(utf8"pid", utf8"BEACON", 1) === false
def hasSameTokensAndAtLeastAda(expected: Value): Boolean
Extension method from Value

Checks that every non-ADA asset of this Value is exactly equal to expected's and its lovelace is at least expected's.

Checks that every non-ADA asset of this Value is exactly equal to expected's and its lovelace is at least expected's.

This is the continuing-output value check. Neither plain comparison is right: === rejects a valid transaction whenever the builder must add lovelace to clear the minimum-ADA requirement, and a whole-value >= lets one output satisfy two "at least" obligations. Tokens exact, ADA open above.

Value parameters

expected

The value the output must carry, up to extra lovelace

Attributes

Returns

true if the non-ADA parts are equal and this value's lovelace is not below expected's

Example 
 val expected = Value.lovelace(2_000_000) + Value(utf8"pid", utf8"TOKEN", 5)
 (expected + Value.lovelace(500_000)).hasSameTokensAndAtLeastAda(expected) === true
 expected.hasSameTokensAndAtLeastAda(expected) === true
 (expected - Value.lovelace(1)).hasSameTokensAndAtLeastAda(expected) === false
 (expected + Value(utf8"pid", utf8"TOKEN", 1)).hasSameTokensAndAtLeastAda(expected) === false
def insertCoin(cs: PolicyId, tn: TokenName, amount: BigInt): Value
Extension method from Value

Returns a new Value with the amount of (cs, tn) set to amount.

Returns a new Value with the amount of (cs, tn) set to amount.

The amount is REPLACED, not added - unlike +. An amount of zero deletes the token, and the policy entry too when it held no other token, keeping the result canonical. Mirrors the CIP-153 insertCoin builtin.

At PV11 (vanRossem) this method lowers to the insertCoin builtin, which requires the value to be in canonical form (strictly ascending keys, no zero amounts, no empty inner maps, keys at most 32 bytes, amounts within the signed 128-bit range) and rejects a cs/tn longer than 32 bytes (for non-zero amount) or an amount outside the signed 128-bit range; a violation makes the script fail. See Options.valueBuiltins.

Value parameters

amount

The new amount; zero deletes the coin

cs

The policy id of the coin to set

tn

The token name of the coin to set

Attributes

Example 
 val value = Value(utf8"pid", utf8"TOKEN", BigInt(5))
 value.insertCoin(utf8"pid", utf8"TOKEN", BigInt(7)) === Value(utf8"pid", utf8"TOKEN", BigInt(7))
 value.insertCoin(utf8"pid", utf8"TOKEN", BigInt(0)) === Value.zero
inline def isPositive: Boolean
Extension method from Value

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.

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

inline def isZero: Boolean
Extension method from Value

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

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
def lovelaceAmount: BigInt
Extension method from Value

Returns the amount of Lovelace in this Value.

Returns the amount of Lovelace in this Value.

This is more efficient version of getLovelace. If the Value contains no lovelace, it fails.

This is useful when we are guaranteed to have lovelace in a Value and want to avoid the overhead of a map lookup. For example, Value in TxOut always has lovelace.

Attributes

Returns

The amount of Lovelace in this Value

Example 
 val value = Value.lovelace(BigInt(1000000))
 value.lovelaceAmount === BigInt(1000000)
inline def nonZero: Boolean
Extension method from Value

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

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
def policyIds: List[PolicyId]
Extension method from Value

A list of all policy ids in that scalus.cardano.onchain.plutus.v1.Value with non-zero tokens.

A list of all policy ids in that scalus.cardano.onchain.plutus.v1.Value with non-zero tokens.

Attributes

Returns

A list of sorted scalus.cardano.onchain.plutus.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
    )
 )
def quantityOf(cs: PolicyId, tn: TokenName): BigInt
Extension method from Value

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

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.

At PV11 (vanRossem) with Options.valueBuiltins enabled (the default) this lowers to the CIP-153 lookupCoin builtin, which requires the value in canonical form (strictly ascending keys, no zero amounts, no empty inner maps, keys at most 32 bytes, amounts within the signed 128-bit range) and makes the script fail otherwise. See Options.valueBuiltins.

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)
inline def showDebug: String
Extension method from Value

Extension alias for Value.debugToString.

Extension alias for Value.debugToString.

Attributes

override def toString: String

Returns a string representation of the object.

Returns a string representation of the object.

The default representation is platform dependent.

Attributes

Returns

a string representation of the object.

Definition Classes
Any
def tokens(cs: PolicyId): SortedMap[TokenName, BigInt]
Extension method from Value

Get all tokens associated with a given policy.

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
inline def unary_-: Value
Extension method from Value

Extension alias for Value.negate.

Extension alias for Value.negate.

Attributes

def withoutLovelace: Value
Extension method from Value

Returns a new Value with the ADA/Lovelace coin removed.

Returns a new Value with the ADA/Lovelace coin removed.

Deletes the (adaPolicyId, adaTokenName) coin - and the empty-policy entry with it when it held no other token - while preserving all other tokens. Equivalent to insertCoin(adaPolicyId, adaTokenName, 0) and shares its PV11 lowering to the CIP-153 insertCoin builtin, including its canonical-form requirement. See Options.valueBuiltins.

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

Inherited methods

def productElementNames: Iterator[String]

Attributes

Inherited from:
Product
def productIterator: Iterator[Any]

Attributes

Inherited from:
Product
def toLedgerValue: Value
Extension method from Value

Converts this Value to a scalus.cardano.ledger.Value

Converts this Value to a scalus.cardano.ledger.Value

Attributes

Throws
IllegalArgumentException

if AssetName exceeds 32 bytes (thrown by AssetName constructor)

Inherited from:
ValueOffchainOps (hidden)
Generated with