stdlib main

cardano/assets

Types

AssetName

A type-alias for ’AssetName`, which are free-form byte-arrays between 0 and 32 bytes.

Alias

AssetName = ByteArray

Lovelace

Lovelace is now a type wrapper for Int.

Alias

Lovelace = Int

PolicyId

A type-alias for a PolicyId. A PolicyId is always 28-byte long

Alias

PolicyId = Hash<Blake2b_224, Script>

Value

A multi-asset output Value. Contains tokens indexed by PolicyId and AssetName.

This type maintain some invariants by construction; in particular, a Value will never contain a zero quantity of a particular token.

Constants 

ada_asset_name: ByteArray = ""

Ada, the native currency, isn’t associated with any AssetName (it’s not possible to mint Ada!).

By convention, it is an empty ByteArray.

ada_policy_id: ByteArray = ""

Ada, the native currency, isn’t associated with any PolicyId (it’s not possible to mint Ada!).

By convention, it is an empty ByteArray.

zero: Value

Construct an empty Value with nothing in it.

Functions

Constructing

from_asset(policy_id: PolicyId, asset_name: AssetName, quantity: Int) -> Value

Construct a Value from an asset identifier (i.e. PolicyId + AssetName) and a given quantity.

from_asset_list(xs: Pairs<PolicyId, Pairs<AssetName, Int>>) -> Value

Promote an arbitrary list of assets into a Value. This function fails (i.e. halt the program execution) if:

  • there’s any duplicate amongst PolicyId;
  • there’s any duplicate amongst AssetName;
  • the AssetName aren’t sorted in ascending lexicographic order; or
  • any asset quantity is null.

This function is meant to turn arbitrary user-defined Data into safe Value, while checking for internal invariants.

from_lovelace(quantity: Int) -> Value

Construct a Value from a lovelace quantity.

Friendly reminder: 1 Ada = 1.000.000 Lovelace

Inspecting

is_zero(self: Value) -> Bool

Check is a Value is zero. That is, it has no assets and holds no Ada/Lovelace.

lovelace_of(self: Value) -> Int

A specialized version of quantity_of for the Ada currency.

policies(self: Value) -> List<PolicyId>

A list of all token policies in that Value with non-zero tokens.

quantity_of(self: Value, policy_id: PolicyId, asset_name: AssetName) -> Int

Extract the quantity of a given asset.

tokens(self: Value, policy_id: PolicyId) -> Dict<AssetName, Int>

Get all tokens associated with a given policy.

Combining

add(
  self: Value,
  policy_id: PolicyId,
  asset_name: AssetName,
  quantity: Int,
) -> Value

Add a (positive or negative) quantity of a single token to a assets. This is more efficient than merge for a single asset.

merge(left: Value, right: Value) -> Value

Combine two Value together.

negate(self: Value) -> Value

Negates quantities of all tokens (including Ada) in that Value.

v1
  |> assets.negate
  |> assets.merge(v1)
  |> assets.is_zero
// True


without_lovelace(self: Value) -> Value

Get a Value excluding Ada.

Transforming

flatten(self: Value) -> List<(PolicyId, AssetName, Int)>

Flatten a Value as list of 3-tuple (PolicyId, AssetName, Quantity).

Handy to manipulate values as uniform lists.

flatten_with(
  self: Value,
  with: fn(PolicyId, AssetName, Int) -> Option<result>,
) -> List<result>

Flatten a Value as a list of results, possibly discarding some along the way.

When the transform function returns None, the result is discarded altogether.

reduce(
  self: Value,
  start: result,
  with: fn(PolicyId, AssetName, Int, result) -> result,
) -> result

Reduce a value into a single result

assets.zero
 |> assets.add("a", "1", 10)
 |> assets.add("b", "2", 20)
 |> assets.reduce(v, 0, fn(_, _, quantity, acc) { acc + quantity })
// 30


to_dict(self: Value) -> Dict<PolicyId, Dict<AssetName, Int>>

Convert the value into a dictionary of dictionaries.

Search Document