cardano/assets
Types
A type-alias for ’AssetName`, which are free-form byte-arrays between 0 and 32 bytes.
Alias
AssetName = ByteArray
Lovelace is now a type wrapper for Int.
Alias
Lovelace = Int
A type-alias for a PolicyId
. A PolicyId
is always 28-byte long
Alias
PolicyId = Hash<Blake2b_224, Script>
Constants
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
.
Functions
Constructing
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
Inspecting
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 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.
Combining
Add a (positive or negative) quantity of a single token to a assets.
This is more efficient than merge
for a single asset.
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.
Transforming
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())
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 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.
Combining
Add a (positive or negative) quantity of a single token to a assets.
This is more efficient than merge
for a single asset.
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.
Transforming
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())
Add a (positive or negative) quantity of a single token to a assets.
This is more efficient than merge
for a single asset.
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.
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())