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 Assets with nothing in it.

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

Construct an Assets map from a builtin Value

Promote an arbitrary list of assets into Assets. 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 Assets, while checking for internal invariants.

Construct Assets from a lovelace quantity.

Friendly reminder: 1 Ada = 1.000.000 Lovelace

Check whether some tokens list is contained within another. This is a specialised version of dict.{contains}.

Check whether local Assets carry a quantity of exactly 1 of at least one asset of the given policy, as expected of an NFT. Other assets are tolerated.

The check is local to the given Assets. A quantity of 1 does not prove that the asset is a genuine NFT, unique across the whole chain. A fungible token present with a quantity of 1 also satisfies the check.

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

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

Check whether Assets carry a quantity of exactly 1 of a single asset of the given policy, as expected of an NFT. Other assets (other than Ada) aren’t tolerated. Said differently, the check succeeds if and only if the assets contain no assets other than the expected NFT or Ada.

See has_any_nft: the check is local to the given Assets and does not prove chain-level uniqueness.

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

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

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

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

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

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

Check whether Assets carry a quantity of exactly 1 of the given asset, as expected of an NFT. Other assets are tolerated.

See has_any_nft: the check is local to the given Assets and does not prove chain-level uniqueness.

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

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

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

assets.has_nft(my_assets, "foo", "token#1") == True
assets.has_nft(my_assets, "foo", "token#2") == True
assets.has_nft(my_assets, "bar", "token#2") == False

Check whether a Assets carry a quantity of exactly 1 of the given asset, as expected of an NFT. Other assets (other than Ada) aren’t tolerated. Said differently, the check succeeds if and only if assets contain no assets other than the expected NFT or Ada.

See has_any_nft: the check is local to the given Assets and does not prove chain-level uniqueness.

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

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

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

assets.has_nft_strict(my_assets, "foo", "token#1") == True
assets.has_nft_strict(my_assets, "foo", "token#2") == False
assets.has_nft_strict(my_assets, "bar", "token#2") == False

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

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

Check if Assets have no assets and holds no Ada/Lovelace.

Efficiently compare two asset maps 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 assets, it defaults to 0.

const my_assets: Assets =
  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(my_assets, datum, >=)

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

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

False == assets.match(assets.zero, datum, fn(_, _) { True })

A version of match which simply ignores lovelace in either operands.

const my_assets: Assets =
  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(my_assets, datum)

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

A specialized version of quantity_of for the Ada currency.

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

Extract the quantity of a given asset.

Get all tokens associated with a given policy.

More efficient version of lovelace_of, but fails when there’s no lovelace quantity in the Assets.

It’s worth noting that:

• There’s always some lovelace in assets from inputs or outputs.
• There’s never any lovelace in assets from mint.

A slightly more efficient version of match which fails if the provided Data is not akin to a Assets.

A slightly more efficient version of match_assets which fails if the provided Data is not akin to a Assets.

More efficient version of quantity_of, but fails if the target policy and asset aren’t present in the assets.

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

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

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

Get Assets excluding Ada.

Removes the first policy id from an Assets map, but fails if the Assets are empty and contains no assets whatsoever.

This is useful to strip Ada forcibly out of assets that are known to contain Ada (e.g. inputs or outputs).

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 Assets together.

Flatten Assets into a list of 3-tuple (PolicyId, AssetName, Quantity).

Handy to manipulate assets as uniform lists.

This function is quite expensive and really only viable in testing scenarios. If you need to traverse all elements in an Assets map, prefer reduce or more bespoke functions for your use case.

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

assets.flatten(my_assets) == assets.flatten_with(my_assets, strategy.triple())

Reduce assets 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 assets into a dictionary of tokens.

Convert assets into pairs of tokens.

Convert assets into a builtin Value

This function is rather expensive and performs a full Data-object conversion. Use with care.