Documentation

The underlying type of the UPLC built-in type Value.

A ByteString with maximum length of maxKeyLen bytes.

A signed 128-bit integer quantity.

Smart constructor for Quantity that validates bounds.

The zero quantity.

Safely add two quantities, checking for overflow.

Unpack a Value into a map from (currency symbol, token name) to quantity.

The map is guaranteed to not contain empty inner map or zero quantity.

Pack a map from (currency symbol, token name) to quantity into a Value.

The map will be filtered so that it does not contain empty inner map or zero quantity.

Total size, i.e., the number of distinct `(currency symbol, token name)` pairs contained in the Value.

Size of the largest inner map.

\(O(\log \max(m, k))\), where \(m\) is the size of the outer map, and \(k\) is the size of the largest inner map.

\(O(\log \max(m, k))\)

\(O(n)\). Scale each token by the given constant factor.

\(O(\log \max(m, k))\)

\(O(m)\), where \(m\) is the size of the outer map. The currency symbols in the Value, in ascending order, including the lovelace currency symbol (the empty bytestring) if present.

The Value restricted to the given currency symbols.

\(O(p \log p + m + n')\), where \(p\) is the length of the policy list, \(m\) is the size of the outer map and \(n'\) is the total size of the result.

Ids the Value does not have, including any longer than maxKeyLen, are ignored. Restricting the outer map can neither empty an inner map nor zero a quantity, so the result is already normalized and this can use pack' rather than pack.

The Value with the given currency symbols removed.

\(O(p \log m + d)\), where \(p\) is the length of the policy list, \(m\) is the size of the outer map and \(d\) is the total size of the dropped currencies.

Ids the Value does not have, including any longer than maxKeyLen, are ignored.

keepPolicies rebuilds the caches by folding its result. This subtracts each dropped currency's contribution instead, so the currencies that stay are never looked at: dropping two of them from a huge Value costs the two, not the whole Value.

\(O(n_{2}\log \max(m_{1}, k_{1}))\), where \(n_{2}\) is the total size of the second Value, \(m_{1}\) is the size of the outer map in the first Value and \(k_{1}\) is the size of the largest inner map in the first Value.

a contains b if for each (currency, token, quantity) in b, lookup currency token a >= quantity.

Both values must not contain negative amounts.

\(O(n_{1}) + O(n_{2})\), where \(n_{1}\) and \(n_{2}\) are the total sizes (i.e., sum of inner map sizes) of the two maps.

Shortcircuits if either value is empty.

Since unionValue is commutative, we switch the arguments whenever the second value is larger in total size than the first one. We have found through experimentation that this results in better performance in practice.

\(O(n)\). Encodes Value as Data, in the same way as non-builtin Value. This is the denotation of ValueData in Plutus V1, V2 and V3.

\(O(n)\). Decodes Data into Value. This is the denotation of UnValueData in Plutus V1, V2 and V3.

Build a Value from a list of entries. It fails unless the following conditions are met:

• currency symbols are strictly ascending
• token names are strictly ascending
• every quantity is within bounds
• no zero quantity