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, the native currency, isn’t associated with any PolicyId (it’s not possible to mint Ada!).

By convention, it is an empty ByteArray.

Construct an empty Value with nothing in it.

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

Promote an arbitrary list of assets into a Value. This function fails (i.e. halts 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.

Construct a Value from a lovelace quantity.

Friendly reminder: 1 Ada = 1.000.000 Lovelace

Check whether a Value carries any NFT from the given policy. Other assets are tolerated.

let value = assets.from_lovelace(42)
   |> assets.add("foo", "asset#1", 1)
   |> assets.add("bar", "asset#2", 14)

assets.has_any_nft(value, "foo") == True
assets.has_any_nft(value, "bar") == False
assets.has_any_nft(value, "baz") == False

Check whether a Value carries any NFT from the given policy. Other assets (other than Ada) aren’t tolerated. Said differently, the check succeeds if and only if the value contains no assets other than the expected NFT or Ada.

let value = assets.from_lovelace(42)
   |> assets.add("foo", "asset#1", 1)
   |> assets.add("bar", "asset#2", 14)

assets.has_any_nft_strict(value, "foo") == False
assets.has_any_nft_strict(value, "bar") == False
assets.has_any_nft_strict(value, "baz") == False

let value = assets.from_lovelace(42)
   |> assets.add("foo", "asset#1", 1)

assets.has_any_nft_strict(value, "foo") == True
assets.has_any_nft_strict(value, "bar") == False

let value = assets.from_lovelace(42)
   |> assets.add("foo", "asset#1", 1)
   |> assets.add("foo", "asset#2", 1)

assets.has_any_nft_strict(value, "foo") == False
assets.has_any_nft_strict(value, "bar") == False

Check whether a Value carries a specific NFT. Other assets are tolerated.

let value = assets.from_lovelace(42)
   |> assets.add("foo", "asset#1", 1)
   |> assets.add("bar", "asset#2", 14)

assets.has_nft(value, "foo", "asset#1") == True
assets.has_nft(value, "foo", "asset#2") == False
assets.has_nft(value, "bar", "asset#2") == False
assets.has_nft(value, "baz", "asset#3") == False

let value = assets.from_lovelace(42)
   |> assets.add("foo", "asset#1", 1)
   |> assets.add("foo", "asset#2", 1)

assets.has_nft(value, "foo", "asset#1") == True
assets.has_nft(value, "foo", "asset#2") == True
assets.has_nft(value, "bar", "asset#2") == False

Check whether a Value carries a specific NFT. Other assets (other than Ada) aren’t tolerated. Said differently, the check succeeds if and only if the value contains no assets other than the expected NFT or Ada.

let value = assets.from_lovelace(42)
   |> assets.add("foo", "asset#1", 1)
   |> assets.add("bar", "asset#2", 14)

assets.has_nft_strict(value1, "foo", "asset#1") == False
assets.has_nft_strict(value1, "bar", "asset#2") == False
assets.has_nft_strict(value1, "baz", "asset#3") == False

let value = assets.from_lovelace(42)
   |> assets.add("foo", "asset#1", 1)

assets.has_nft_strict(value, "foo", "asset#1") == True
assets.has_nft_strict(value, "foo", "asset#2") == False
assets.has_nft_strict(value, "bar", "asset#2") == False

let value = assets.from_lovelace(42)
   |> assets.add("foo", "asset#1", 1)
   |> assets.add("foo", "asset#2", 1)

assets.has_nft_strict(value3, "foo", "asset#1") == False
assets.has_nft_strict(value3, "foo", "asset#2") == False

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

Efficiently compare two values together, allowing a custom behaviour for Ada/Lovelace. The second parameter is provided as Data, allowing to conveniently compare serialized datums or similar structurually equivalent types (such as Pairs<PolicyId, Pairs<AssetName, Lovelace>>).

The third argument is a callback function to assert the left and right lovelace quantities. Its first argument refers to the quantity of the first argument of match, and the second argument of the callback to the quantity of the second argument of match. In the absence of lovelace in any value, it defaults to 0.

const value: Value =
  assets.from_lovelace(30)
    |> assets.add("foo", "bar", 1)
    |> assets.add("foo", "baz", 42)

const datum: Data =
  assets.from_lovelace(20)
    |> assets.add("foo", "bar", 1)
    |> assets.add("foo", "baz", 42)

True == assets.match(value, datum, >=)

False == assets.match(value, datum, ==)

True == assets.match(value, datum, fn(value_lovelace, datum_lovelace) {
  2 * datum_lovelace >= value_lovelace
})

A specialized version of quantity_of for the Ada currency.

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

Extract the quantity of a given asset.

Get all tokens associated with a given policy.

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

Combine two Value together.

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

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

Get a subset of the assets restricted to the given policies.

Get a Value excluding Ada.

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

Handy to manipulate values as uniform lists.

Flatten a Value as a list of results, possibly discarding some along the way. In particular, we have:

flatten(value) === flatten_with(value, strategy.triple())

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

Convert the value into a dictionary of dictionaries.