aiken/builtin

This modules contains all the Plutus builtins recognized by Aiken.

It’s important to note that many of those functions are partial and will halt the execution of the Plutus virtual machine on failure. They also all rely on call-by-value, which means that function arguments are eagerly evaluated.

Functions

Integer

add_integer(left: Int, right: Int) -> Int

Minimum Plutus Version1

Adds two integers (+).

subtract_integer(left: Int, right: Int) -> Int

Minimum Plutus Version1

Subtract two integers (-).

multiply_integer(left: Int, right: Int) -> Int

Minimum Plutus Version1

Multiple two integers (*).

divide_integer(numerator: Int, denominator: Int) -> Int

Minimum Plutus Version1

Integer division truncated towards negative infinity (/).

quotient_integer(numerator: Int, denominator: Int) -> Int

Minimum Plutus Version1

Integer division truncated towards zero.

remainder_integer(numerator: Int, denominator: Int) -> Int

Minimum Plutus Version1

Integer remainder, satisfying

quotient_integer(x, y) * y + remainder_integer(x, y) == x

mod_integer(numerator: Int, denominator: Int) -> Int

Minimum Plutus Version1

Integer modulus (%), satisfying

divide_integer(x, y) * y + mod_integer(x, y) == x

equals_integer(left: Int, right: Int) -> Bool

Minimum Plutus Version1

Integer equality.

less_than_integer(left: Int, right: Int) -> Int

Minimum Plutus Version1

Integer strict inequality.

less_than_equals_integer(left: Int, right: Int) -> Int

Minimum Plutus Version1

Integer inequality.

integer_to_bytearray(endianness: Bool, size: Int, value: Int) -> ByteArray

Minimum Plutus Version3

Convert an integer value into a ByteArray.

  • The first arguments / specifies the endianness:

    boolean valueendianness
    TrueBig endian
    FalseLittle endian
  • The second argument indicates the target size (in bytes) of the final ByteArray. This allows to allocate a specific number of bytes in advance. The function fails if the given value cannot fit in the requested size or if the value is negative. However, a size of 0 will yield a ByteArray that is precisely as large as necessary to fit the value.

Bytearray

Constructing

append_bytearray(left: ByteArray, right: ByteArray) -> ByteArray

Minimum Plutus Version1

Concatenate two bytearrays together.

cons_bytearray(byte: Int, bytes: ByteArray) -> ByteArray

Minimum Plutus Version1

Push a byte in front of a bytearray.

replicate_byte(length: Int, byte: Int) -> ByteArray

Minimum Plutus Version2

Construct a ByteArray from the repetition of the same byte a specific number of times. Fails if the byte is out-of-bound or if the length is negative.

Inspecting

count_set_bits(self: ByteArray) -> Int

Minimum Plutus Version2

Count the number of bits set in the given ByteArray.

find_first_set_bit(self: ByteArray) -> Int

Minimum Plutus Version2

Find the index of the first bit set. Note that bits are indexed from the end (see also read_bit for more details).

index_bytearray(bytes: ByteArray, index: Int) -> Int

Minimum Plutus Version1

Access the byte at the given index in the bytearray.

length_of_bytearray(bytes: ByteArray) -> Int

Minimum Plutus Version1

Number of bytes in a bytearray.

read_bit(self: ByteArray, index: Int) -> Bool

Minimum Plutus Version2

Read a particular bit (True if set) at the given index. Fails if the index is out-of-bounds. Note that the index reads from the end. For example, consider the byte 0xF4 and an index i:

i=7i=6i=5i=4i=3i=2i=1i=0
11110100

So, we have:

read_bit(#[0xF4], 0) == False
read_bit(#[0xF4], 1) == False
read_bit(#[0xF4], 2) == True
read_bit(#[0xF4], 3) == False
read_bit(#[0xF4], 4) == True
read_bit(#[0xF4], 5) == True
read_bit(#[0xF4], 6) == True
read_bit(#[0xF4], 7) == True
read_bit(#[0xF4, 0xF4], 8) == False

slice_bytearray(start: Int, len: Int, bytes: ByteArray) -> ByteArray

Minimum Plutus Version1

Extract a sub-array from a bytearray given starting and length of the sub-array.

Comparing

equals_bytearray(left: ByteArray, right: ByteArray) -> Bool

Minimum Plutus Version1

Bytearray equality.

less_than_bytearray(left: ByteArray, right: ByteArray) -> Bool

Minimum Plutus Version1

Bytearray strict inequality.

less_than_equals_bytearray(left: ByteArray, right: ByteArray) -> Bool

Minimum Plutus Version1

Bytearray inequality.

Bitwise

and_bytearray(padded: Bool, left: ByteArray, right: ByteArray) -> ByteArray

Minimum Plutus Version2

Logical AND applied to two bytearrays. The first argument indicates whether padding semantics should be used. If this argument is False, truncation semantics are used instead.

or_bytearray(padding: Bool, left: ByteArray, right: ByteArray) -> ByteArray

Minimum Plutus Version2

Logical OR applied to two bytearrays. The first argument indicates whether padding semantics should be used. If this argument is False, truncation semantics are used instead.

xor_bytearray(padding: Bool, left: ByteArray, right: ByteArray) -> ByteArray

Minimum Plutus Version2

Logical XOR applied to two bytearrays. The first argument indicates whether padding semantics should be used. If this argument is False, truncation semantics are used instead.

complement_bytearray(self: ByteArray) -> ByteArray

Minimum Plutus Version2

Logical bitwise complement of the bytearray (set becomes unset, and unset becomes set).

Shifting

rotate_bytearray(self: ByteArray, offset: Int) -> ByteArray

Minimum Plutus Version2

Like shift_bytearray but instead of introducing zeroes in holes, use the bits that are dropped from either ends.

rotate_bytearray(#[0xEB, 0xFC], 5) == #[0x7F, 0x9D]
rotate_bytearray(#[0xEB, 0xFC], -8) == #[0xFC, 0xEB]
rotate_bytearray(#[0xEB, 0xFC], 8) == #[0xFC, 0xEB]

shift_bytearray(self: ByteArray, offset: Int) -> ByteArray

Minimum Plutus Version2

Shift bits in a ByteArray by the given offset, replacing holes with zeroes. The offset can be positive (left-shift) or negative (right-shift).

shift_bytearray(#[0xEB, 0xFC], 5) == #[0x7F, 0x80]
shift_bytearray(#[0xEB, 0xFC], -8) == #[0x00, 0xEB]
shift_bytearray(#[0xEB, 0xFC], 8) == #[0xFC, 0x00]

Transforming

bytearray_to_integer(endianness: Bool, bytes: ByteArray) -> Int

Minimum Plutus Version3

Convert a ByteArray to an integer value. The first argument specifies the endianness:

boolean valueendianness
TrueBig endian
FalseLittle endian

String

append_string(left: String, right: String) -> String

Minimum Plutus Version1

Concatenate two strings.

equals_string(left: String, right: String) -> Bool

Minimum Plutus Version1

String equality.

encode_utf8(str: String) -> ByteArray

Minimum Plutus Version1

Convert a string into a UTF-8 encoded array of bytes.

decode_utf8(bytes: ByteArray) -> String

Minimum Plutus Version1

Interpret a UTF-8 encoded array of bytes as a String. Fails if the bytes aren’t UTF-8 encoded.

List

new_list() -> List<Data>

Minimum Plutus Version1

Construct an empty list of Data.

cons_list(elem: a, list: List<a>) -> List<a>

Minimum Plutus Version1

Push an element in front of a list.

head_list(list: List<a>) -> a

Minimum Plutus Version1

The head of a list. Fails if empty.

tail_list(list: List<a>) -> List<a>

Minimum Plutus Version1

The tail of a list. Fails if empty.

null_list(list: List<a>) -> Bool

Minimum Plutus Version1

True when a list is empty.

choose_list(list: List<a>, when_empty: b, when_non_empty: b) -> b

Minimum Plutus Version1

Select a branch to continue with depending on whether the list is empty or not.

Data

constr_data(index: Int, fields: List<Data>) -> Data

Minimum Plutus Version1

Construct a Data from a constructor index and a list of fields.

un_constr_data(data: Data) -> (Int, List<Data>)

Minimum Plutus Version1

Interpret a Data as a constructor. Fails if it’s not a constructor.

unconstr_fields(data: Data) -> List<Data>

Minimum Plutus Version1

Interpret a Data as a constructor and extract its fields. Slightly more efficient than using un_constr_data.

unconstr_index(data: Data) -> Int

Minimum Plutus Version1

Interpret a Data as a constructor and extract its index. Slightly more efficient than using un_constr_data.

map_data(items: List<Pair<Data, Data>>) -> Data

Minimum Plutus Version1

Construct a Data from a list of pairs.

un_map_data(data: Data) -> List<Pair<Data, Data>>

Minimum Plutus Version1

Interpret a Data as a map. Fails if it’s not a map.

list_data(items: List<Data>) -> Data

Minimum Plutus Version1

Construct a Data from a list of elements.

un_list_data(data: Data) -> List<Data>

Minimum Plutus Version1

Interpret a Data as a list. Fails if it’s not a list.

i_data(i: Int) -> Data

Minimum Plutus Version1

Construct a Data from an integer.

un_i_data(data: Data) -> Int

Minimum Plutus Version1

Interpret a Data as a integer. Fails if it’s not an integer.

b_data(bytes: ByteArray) -> Data

Minimum Plutus Version1

Construct a Data from a ByteArray

un_b_data(data: Data) -> ByteArray

Minimum Plutus Version1

Interpret a Data as a bytearray. Fails if it’s not a bytearray.

equals_data(left: Data, right: Data) -> ByteArray

Minimum Plutus Version1

Equality on Data.

serialise_data(data: Data) -> ByteArray

Minimum Plutus Version2

Serialise a Data to bytes, using CBOR.

choose_data(
  data: Data,
  when_constr: a,
  when_map: a,
  when_list: a,
  when_int: a,
  when_bytearray: a,
) -> a

Minimum Plutus Version1

Select a branch to continue with based on what the Data actually is.

Pair

new_pair(left: Data, right: Data) -> Pair<Data, Data>

Minimum Plutus Version1

Construct a Data from a pair of elements.

new_pairs() -> Pairs<Data, Data>

Minimum Plutus Version1

Construct an empty list of pairs of data.

fst_pair(pair: Pair<a, b>) -> a

Minimum Plutus Version1

Get the first element of a pair.

snd_pair(pair: Pair<a, b>) -> b

Minimum Plutus Version1

Get the second element of a pair.

Crypto

Hashing

blake2b_256(preimage: ByteArray) -> ByteArray

Minimum Plutus Version1

Calculate the blake2b-256 hash digest value of a given bytearray. Output is always 32-byte long.

blake2b_224(preimage: ByteArray) -> ByteArray

Minimum Plutus Version3

Calculate the blake2b-224 hash digest value of a given bytearray. Output is always 28-byte long.

keccak_256(preimage: ByteArray) -> ByteArray

Minimum Plutus Version3

Calculate the keccak-256 hash digest value of a given bytearray. Output is always 32-byte long.

ripemd_160() -> a

Minimum Plutus Version2

Calculate the ripemd-160 hash digest value of a given bytearray. Output is always 20-byte long.

sha2_256(preimage: ByteArray) -> ByteArray

Minimum Plutus Version1

Calculate the SHA2-256 hash digest value of a given bytearray. Output is always 32-byte long.

sha3_256(preimage: ByteArray) -> ByteArray

Minimum Plutus Version1

Calculate the SHA3-256 hash digest value of a given bytearray. Output is always 32-byte long.

ECDSA

verify_ed25519_signature(
  verification_key: ByteArray,
  message: ByteArray,
  signature: ByteArray,
) -> ByteArray

Minimum Plutus Version1

Verify an Ed25519 signature from a associated verification key.

verify_ecdsa_secp256k1_signature(
  verification_key: ByteArray,
  message: ByteArray,
  signature: ByteArray,
) -> ByteArray

Minimum Plutus Version2

Verify an ECDSA-SECP256k1 signature from a associated verification key.

verify_schnorr_secp256k1_signature(
  verification_key: ByteArray,
  message: ByteArray,
  signature: ByteArray,
) -> ByteArray

Minimum Plutus Version2

Verify a SCHNORR-SECP256k1 signature from a associated verification key.

Pairing

bls12_381_g1_add(a: G1Element, b: G1Element) -> G1Element

Minimum Plutus Version3

bls12_381_g1_neg(self: G1Element) -> G1Element

Minimum Plutus Version3

bls12_381_g1_scalar_mul(scalar: Int, self: G1Element) -> G1Element

Minimum Plutus Version3

bls12_381_g1_equal(self: G1Element, other: G1Element) -> Bool

Minimum Plutus Version3

bls12_381_g1_compress(self: G1Element) -> ByteArray

Minimum Plutus Version3

bls12_381_g1_uncompress(self: ByteArray) -> G1Element

Minimum Plutus Version3

bls12_381_g1_hash_to_group(
  group: ByteArray,
  domain_separation_tag: ByteArray,
) -> G1Element

Minimum Plutus Version3

bls12_381_g2_add(a: G2Element, b: G2Element) -> G2Element

Minimum Plutus Version3

bls12_381_g2_neg(self: G2Element) -> G2Element

Minimum Plutus Version3

bls12_381_g2_scalar_mul(scalar: Int, self: G2Element) -> G2Element

Minimum Plutus Version3

bls12_381_g2_equal(self: G2Element, other: G2Element) -> Bool

Minimum Plutus Version3

bls12_381_g2_compress(self: G2Element) -> ByteArray

Minimum Plutus Version3

bls12_381_g2_uncompress(self: ByteArray) -> G2Element

Minimum Plutus Version3

bls12_381_g2_hash_to_group(
  group: ByteArray,
  domain_separation_tag: ByteArray,
) -> G2Element

Minimum Plutus Version3

bls12_381_miller_loop(g1: G1Element, g2: G2Element) -> MillerLoopResult

Minimum Plutus Version3

bls12_381_mul_miller_loop_result(
  a: MillerLoopResult,
  b: MillerLoopResult,
) -> MillerLoopResult

Minimum Plutus Version3

bls12_381_final_verify(a: MillerLoopResult, b: MillerLoopResult) -> Bool

Minimum Plutus Version3

Miscellaneous

choose_void(void: Void, when_void: a) -> a

Minimum Plutus Version1

Continue with the continuation when the given term is Void.

debug(message: String, continuation: a) -> a

Minimum Plutus Version1

Trace the provided message, and continue with the continuation.

if_then_else(condition: Bool, when_true: a, when_false: a) -> a

Minimum Plutus Version1

Return first computation when the condition is true, and the second otherwise.

Search Document