stdlib v1.8.0

aiken/transaction/value

Types

AssetName

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

Alias

AssetName = ByteArray

MintedValue

A multi-asset value that can be found when minting transaction. It always holds a null quantity of Ada. Note that because of historical reasons, this is slightly different from Value found in transaction outputs.

Note that you’re never expected to construct a MintedValue yourself. If you need to manipulate multi-asset values, use Value

See also from_minted_value.

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.

Functions 

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

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

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.

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: List<(PolicyId, List<(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

from_minted_value(self: MintedValue) -> Value

Convert a MintedValue into a Value.

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.

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
  |> value.negate
  |> value.merge(v1)
  |> value.is_zero
// True


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.

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

Reduce a value into a single result

value.zero()
 |> value.add("a", "1", 10)
 |> value.add("b", "2", 20)
 |> value.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.

to_minted_value(self: Value) -> MintedValue

Convert a Value into a MintedValue.

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

Get all tokens associated with a given policy.

without_lovelace(self: Value) -> Value

Get a Value excluding Ada.

zero() -> Value

Construct an empty Value with nothing in it.

Search Document