Skip to main content

Builtins

A B

abs(t : T)

Returns the absolute value of input t.

When t is of type:

  • int, abs(t) is typed nat
  • rational, abs(t) is typed rational

The function may be considered as a non-failing conversion function from int to nat.

Parameter


t :

T

Value of type int or rational

Returns


R

Absolute value of t

Fails with

does not fail


Michelson


Related

add(s : set<T>, e : T)

Returns a copy of set s augmented with element e.

If e is already present in s, it returns a copy of s.

Parameters


s :

Input set


e :

T

Element to add

Returns


Set that contains all elements of s and element e

Fails with

does not fail


Michelson


Related

address_to_contract<T>(a : address)

Converts address a to a contract<T> value to be used as parameter of make_operation.

T is:

  • unit for an account address (tz1...)
  • the type of the parameter section for a contract address
When the contract's parameter is annotated it is easier to use get_entrypoint builtin.

Parameter


Address to convert

Returns


option<contract<T>>

  • none when the address or the path to entrypoint is invalid
  • some of a contract<T> value

Fails with

does not fail


Related

apply_lambda(f : lambda<A * T, R>, x : A)

Executes partial application of a lambda value f to an argument value x.

For example:

const plus_x = lambda<nat>((a : nat * nat) -> a[0] + a[1]);
const plus_three = apply_lambda(plus_x, 3);
const r = exec_lambda(plus_three, 1);
/* r is equal to 4 */

Parameters


f :

lambda<A*T,R>

Lambda to partially apply


x :

A

Lambda argument

Returns


Partially applied lambda value

Fails with

does not fail


Michelson


Related

blake2b(b : bytes)

Hashes bytes value with blake2b algorithm.

Parameter


b :

Array of byte to hash

Returns


Hash of bytes b

Fails with

does not fail


Michelson


Related

C D

call_view<T>(a : address, id : string, arg : X)

Calls a contract's view and returns an option<T> of the result.

For example, consider the following view declaration in contract A:

view affine(x : rational) : rational {
return (2 * x + 3)
}

Call this function from contract B with:

const r ?= call_view<rational>(addr_A, "affine", -3/2) : "AFFINE_ERR"

Parameters


Address of the contract to call


id :

Name of the view; must be a string literal (e.g. "my_view")


arg :

X

Argument of the called view

Returns


  • none if a problem occured (view not found, or view execution failed)
  • some(v), v being the value returned by the view

Fails with

does not fail


Michelson


Related

ceil(r : rational)

Converts a rational to an int with ceiling policy

Parameter

Returns


Ceiled integer

Fails with

does not fail


Related

check_signature(k : key, s : signature, b : bytes)

Checks whether signature s is obtained by signing sequence of bytes b with account public key k.

Parameters


k :

Public key of the account to sign b.


Signature to be compared with the one obtained by signing b with k.


b :

Sequence of bytes to sign with k and to compare to s.

Returns


Returns true if s is obtained by signing b with k, false otherwise.

Fails with

does not fail


Michelson


Related

concat

Concatenates two values of type string, bytes, or list<T>, or a list of values of type string or bytes.

String

Concatenates two string values.

For example:

const m = concat("Hello ", "Archetype");
/* m is "Hello Archetype" */

It is equivalent to the + operator.

Bytes

Concatenates two bytes values.

For example:

const m = concat(0x48656c6c6f, 0x417263686574797065);
/* m is 0x48656c6c6f417263686574797065 */

List

Concatenates two lists of any element of any type.

It is equivalent to the following code:

var res : list<T> = l;
for e in reverse(L) do
res.prepend(e)
done;
L := res

For example:

const l = concat([1; 2; 3], [4; 5]);
/* l is [1; 2; 3; 4; 5] */

List of values

Concatenates values of a list, of type string or bytes

For example:

const m = concat([ "Hello "; "Archetype "; "world!" ]);
/* m is "Hello Archetype world!"*/

Returns


T

Concantenation of 2 values or list of values of type

Fails with

does not fail


Michelson


Related

contains(c : C, e : T)

Tests whether element e is contained in c or not.

Parameters


e :

T

Element to test

Returns


  • true when e is contained in c
  • false when e is not contained in c

Fails with

does not fail


Michelson


Related

contract_to_address(c : contract<T>)

Returns the address of a contract.

Parameter


Contract to get the address of

Returns


Address of c

Fails with

does not fail


Related

create_contract(path, delegator, amount, storage)

Creates an operation for contract creation. This operations is then added to the operations builtin list of generated operations.

For example, in order to create contract from source ./tests/simple.tz for 0 as natural initial storage:

const storage_init : nat = 0;
const op_addr : (operation * address) =
create_contract("./tests/simple.tz", none, 0tz, storage_init);
operations := [op_addr[0]]

It is also possible to import the contract with:

import simple from "./tests/simple.tz"

and deploy it with:

const storage_init : nat = 0;
const op_addr : (operation * address) =
create_contract(simple, none, 0tz, storage_init);
operations := [op_addr[0]]
info

The import of archetype contract (from .arl file) will be available in next releases.

Parameters


path :

string literal

Path to Michelson code file to create (*.tz)


del :

option<address>

Option of delegate address


tez :

Amount of balance to transfer to new contract


storage :

any

Initial storage value

Returns


operation * address

Returns a pair of:
  • Operation for contract creation
  • Address of created contract

Fails with

does not fail


Michelson


Related

create_ticket(s : T, n : nat)

Creates a ticket from a value typed T and an amount.

Parameters


s :

T

The information of the ticket


n :

The amount of the ticket

Returns


Created ticket

Fails with

does not fail


Michelson


Related

E F

exec_lambda(f : lambda<T, R>, x : T)

Applies a lambda value f to argument x.

For example:

const plus_three = lambda((x : nat) -> x + 3);
const r = exec_lambda(plus_three, 1);
/* r is equal to 4 */

Parameters


Lambda to execute


x :

T

Argument

Returns


Evaluation of f(x)

Fails with

does not fail


Michelson


Related

floor(r : rational)

Converts a rational to an int with floor policy

Parameter

Returns


Floored integer

Fails with

does not fail


Related

fold (i : or<L, R>, f : L -> or<L, R>)

fold applies the inlined function f to the left of initial value i:

  • if it returns a left value, it applies f to the result of f(i), and iteratively applies f on as long as it returns a left value.
  • if it returns a right value, iteration stops, and the right value is returned.

Hence the application may be represented as: fold(i, f) = right(f(...(f(i))))

For example, the following expression reverses the list l typed list<nat>:

var empty : list<nat> = [];
var p : or<list<nat> * list<nat>, list<nat>> = left<list<nat>> ((empty, l));
res := fold (p, x ->
match x[1] with
| hd::tail -> left<list<nat>> ((prepend(x[0], hd), tail))
| [] -> right<list<nat> * list<nat>>(x[0])
end
)
note

Folded function is inlined and cannot be a lambda variable.

Parameters


Initial value


f :

function

Inlined folding function that:
  • takes a parameter of type L
  • returns a values of type or<L, R>

Returns


R

Folded value

Fails with

does not fail


Michelson


Related

G H

get_entrypoint<T>(s, a : address)

Returns an option of contract's entrypoint (typed contract<T>) to the entrypoint s with argument T at contract address a.

For example, consider the following contract at address a:

archetype example

entry exec(n : nat) { /* ... */ }

The exec entrypoint may be retrieved with:

const e = get_entrypoint("%exec", a) ? the : fail("EXEC_NOT_FOUND")

The entrypoint may then be used as an argument of make_operation.

Parameters


s :

string literal

Entrypoint name as string literal prefixed by %


Address of the entrypoint's contract

Returns


option<contract<T>>

Option of entrypoint as a contract value

Fails with

does not fail


Michelson


Related

greedy_and(a : bool, b : bool)

Greedy evaluation of boolean conjonction of a and b, meaning that b is evaluated even if a is false.

Parameters


a :

Boolean input


b :

Boolean input

Returns


true if a and b are true, false otherwise.

Fails with

does not fail


Michelson


Related

greedy_or(a : bool, b : bool)

Greedy evaluation of boolean disjonction of a and b, meaning that b is evaluated even if a is true.

Parameters


a :

Boolean input


b :

Boolean input

Returns


true if a or b is true, false otherwise.

Fails with

does not fail


Michelson


Related

I J

int_to_date(i : int)

Converts an integer value i to a date, where i is considered as a tiemstamp value, that is the number of seconds since 1970-01-01.

Parameter


i :

The timestamp to convert

Returns


Date corresponding to timestamp i

Fails with

does not fail


Related

int_to_nat(i : int)

Converts an int value to an option` of nat value.

Parameter


i :

Integer to convert

Returns


option<nat>

Optional natural value:
  • some(n) when i is positive
  • none otherwise

Fails with

does not fail


Michelson


Related

is_none(o : option<T>)

Returns false if an optional value o is some, true otherwise.

It is equivalent to the following expression:

o ? false : true

or equivalently:

match o with
| some(v) -> false
| none -> true
end

Parameter


Optional value to test if it is none

Returns


  • true when o is none
  • false when o is some

Fails with

does not fail


Related

is_some(o : option<T>)

Returns true if an optional value o is some, false otherwise.

It is equivalent to the following expression:

o ? true : false

or equivalently:

match o with
| some(v) -> true
| none -> false
end

Parameter


Optional value to test if it is some

Returns


  • true when o is some
  • false when o is none

Fails with

does not fail


Related

join_tickets(t1 : ticket<T>, t2 : ticket<T>)

Joins two compatible tickets (same value, same origin contract).

Parameters


First ticket to join


Second ticket to join

Returns


option<ticket<T>>

Joined ticket

Fails with

does not fail


Michelson


Related

keccak(b : bytes)

K L

Hashes bytes value with keccak algorithm.

Parameter


b :

Array of byte to hash

Returns


Hash of b

Fails with

does not fail


Michelson


Related

key_hash_to_contract(pkh : key_hash)

Converts key_hash to contract.

Parameter


pkh :

key hash to convert

Returns


contract<unit>

The extracted contract unit

Fails with

does not fail


Michelson


Related

key_to_address(k : key)

Converts a key to an address

Parameter


k :

Key to convert

Returns


Key converted to address

Fails with

does not fail


Related

key_to_key_hash(k : key)

Converts a key to key_hash.

Parameter


k :

key to hash

Returns


hashed value of k

Fails with

does not fail


Michelson


Related

left<(L,)? T>(x : L)

Constructs a left value typed or<L, R>.

The left type L may be omitted as it can be inferred, but the right type R is mandatory.

For example:

const o = left<string>(2)

o is then typed option<nat, string>. It is equivalent to:

const o = left<nat, string>(2)

Parameter


x :

L

Value to convert

Returns


Value converted to left literal

Fails with

does not fail


Michelson


Related

length(o : T)

Returns the length of a string or bytes value, or the number of elements of a container.

Parameter

Returns


Length or size of argument o

Fails with

does not fail


Michelson


Related

M N

make_asset(k : asset_key<A>, v : asset_value<A>)

Creates an asset from identifier and data (key and value).

It is typically convenient when an asset data is provided as an entry point parameter.

Consider for example the following asset declaration:

asset vehicle {
vin : string;
nbrepairs : nat = 0;
dateofrepair : date = now;
}

The add_vehicle entry point below provides a vehicle data as a record:

entry add_vehicle(k : asset_key<vehicle>, d : asset_value<vehicle>) {
vehicle.put(make_asset(k, d))
}

Parameters


Asset identifier


Asset value

Returns


A

Asset literal with identifier k and data v.

Fails with

does not fail


Related

make_big_map<K, V>(m)

Makes a big_map from literal or variable.
This is useful to solve the type amiguity of literals, like for example the empty big_map [].

Parameter


Big_map

Returns


Returns big_map

Fails with

does not fail

make_map<K, V>(m)

Makes a map from literal or variable.
This is useful to solve the type amiguity of literals, like for example the empty map [].

Parameter


Map

Returns


Returns map

Fails with

does not fail

make_list<T>(l)

Makes a list from literal or variable.
This is useful to solve the type amiguity of literals, like for example the empty list [].

Parameter


List

Returns


Returns list

Fails with

does not fail

make_operation(a : tez, c : contract<T>, arg : T)

Makes an operation.

Parameters


a :

The amount of tez sent with the operation


Entrypoint with argument of type T (as returned by get_entrypoint)


arg :

T

The argument of the called entrypoint

Returns


The generated operation

Fails with

does not fail


Michelson


Related

make_set<T>(s)

Makes a set from literal or variable.
This is useful to solve the type amiguity of literals, like for example the empty set [].

Parameter


s :

Set

Returns


Returns set

Fails with

does not fail

map

Maps a value of type list<T>, map<K, V>, or option<T>.

List

Applies an inlined function of type T -> T on each element of a list of elements typed T and returns a new list.

For example:

const l = map([ 1; 2 ; 3 ], x -> 2 * x + 1);
/* l is [ 3; 5; 7 ] */

Map

Applies an inlined function of type (K * V) -> V on each value of a map with key of type K and value of type V; it returns a new map.

For example:

const m = map([ ("a", 5); ("b", 6); ("c", 7) ], x -> 2 * x[1] + 1)
/* m is [ ("a", 11); ("b", 13); ("c", 15) ] */

Note that the x intput of the inlined mapping function is a pair (key and value) of the map; hence x[0] is the key and x[1] is the value.

Option

Applies an inlined function of type T -> T to the some value of an option<T> value, or returns none.

For example:

const o1 = map(some(2), x -> 2 * x + 1);
/* o1 is some(5) */
const o2 = map(none, x -> 2 * x + 1);
/* o2 is none */

Note that the ? : syntax is also available to fold an option. The above example is then equivalent to:

const o1 = some(2) ? 2 * the + 1 : none;
/* o1 is some(5) */

Parameters


s :

-

Input to map of type:


f :

function

Inlined mapping function.

Returns


-

Returns a mapped value of the same type as the input.

Fails with

does not fail


Michelson


Related

max(a : T, b : T)

Returns maximum value between a and b

Parameters


a :

T

First element to compare


b :

T

Second element to compare

Returns


Maximum value. T must be a comparable type.

Fails with

does not fail


Related

min(a : T, b : T)

Returns minimum value between a and b

Parameters


a :

T

First element to compare


b :

T

Second element to compare

Returns


Minimum value. T must be a comparable type.

Fails with

does not fail


Related

mutez_to_nat(v : tez)

Converts a tez value in mutez (millionth of tez) to a nat value.

For example:

const n = mutez_to_nat(5tz);
/* n is 5000000 */

Parameter


v :

The amount of tez to convert

Returns


The amount of mutez

Fails with

does not fail


Related

nat_to_string(n : nat)

Converts a natural to a string.

Parameter


n :

Nat to convert

Returns


String converted to nat

Fails with

does not fail


Related

none<T>

Optional none value for type option<T>.

Returns


Value none

Fails with

does not fail


Michelson


Related

nth(l : list<T>, n : nat)

Returns an option of the nth element of list l.

warning

Implementation is in O(n) complexity (Michelson lists are linked).

Parameters


List of elements typed T


n :

Position in range 0 to length(l)-1

Returns


  • some of element at position n
  • none when n is out of bound

Fails with

does not fail


Related

O P

open_chest(k : chest_key, c : chest, t : nat)

Opens chest c with key k under time t.

Parameters


Chest key


c :

Chest


t :

"Time" (number of operations) used to lock the chest

Returns


or<bytes, bool>

The returned value has 3 possible values:
  • left(v), v being the value in the chest
  • right(true) when chest key k does not open the chest
  • right(false) when chest key k opens the chest but t parameter is not the value used to lock the chest

Fails with

does not fail


Michelson


Related

pack(o : T)

Serializes any value of packable type to a bytes representation.

Parameter


o :

T

Value of packable type T

Returns


Packed value

Fails with

does not fail


Michelson


Related

pairing_check(l : list<bls12_381_g1 * bls12_381_g2>)

Checks pairing of pairs of BLS values.

Parameter


l :

list<bls12_381_g1 * bls12_381_g2>

List of pairs of bls curves

Returns


The result

Fails with

does not fail


Michelson


Related

prepend(l : list<T>, e : T)

Adds element e at the beginning of list l.

Parameters


List


e :

T

Element to add

Returns


List with element e followed by list l of elements.

Fails with

does not fail


Michelson


Related

put(m : map<K, V>, k : K, v : V)

Associates value v with key k in map (map, big_map or iterable_map)m.

Parameters


k :

K

Key to put


v :

V

Value to put

Returns


Copy of map m whith new key-value pair (returns same type as m)

Fails with

does not fail


Michelson


Related

Q R

read_ticket(t : ticket<T>)

Reads ticket's origin contract, value and amount.

Parameter


Ticket to read

Returns


address * T * nat

Tuple of ticket's address of origin contract, value and the amount

Fails with

does not fail


Michelson


Related

remove(c : C, i : T)

Returns a copy of c without item i.

Parameters


c :

C

Container to remove element from; C is either:


i :

T

Item to remove (key value for map containers).

Returns


Container that contains all elements from c except i

Fails with

does not fail


Michelson


Related

reverse(l : list<T>)

Returns a copy of list l with elements in reverse order.

Parameter


List to reverse

Returns


List with reversed elements

Fails with

does not fail


Related

right<T(, R)>(x : R)

Constructs a right value typed or<L, R>.

The left type L is mandatory, while the right type R may be omited as it can be inferred.

For example:

const o = right<nat>("abc")

o is then typed option<nat, string>. It is equivalent to:

const o = right<nat, string>("abc")

Parameter


x :

R

Value to convert

Returns


Value converted to right literal

Fails with

does not fail


Michelson


Related

S T

sapling_empty_state(k : key_hash)

Creates a sapling state with the specified memo size. The memo is an arbitrary string message encrypted and available to anyone owning the outgoing viewing key.

Parameter


n :

Memo size

Returns


The fresh sapling state

Fails with

does not fail


Michelson


Related

sapling_verify_update(s, t)

Applies sapling transaction on sapling state.

Parameters


Sapling state


Sapling transaction

Returns


option<bytes * int * sapling_state(n)>

The result

Fails with

does not fail


Michelson


Related

set_delegate(opkh : option<key_hash>)

Sets delegate account for current contract.

Parameter


  • none remove delegation of current contract
  • some(pkh) update delegation of current contract with address behind pkh

Returns


Operation of type

Fails with

does not fail


Michelson


Related

sha256(b : bytes)

Hashes bytes value with sha256 algorithm.

Parameter


b :

Message to be hashed

Returns


Hash of b bytes

Fails with

does not fail


Michelson


Related

sha3(b : bytes)

Hashes bytes value with sha3 algorithm.

Parameter


b :

Message to be hashed

Returns


Hash of b bytes

Fails with

does not fail


Michelson


Related

sha512(b : bytes)

Hashes bytes value with sha512 algorithm.

Parameter


b :

Message to be hashed

Returns


Hash of b bytes

Fails with

does not fail


Michelson


Related

slice(s : T, o : nat, l : nat)

Extracts a section of a string or bytes s and returns it as a new string or bytes.

The section starts at offset postion o is has a length of l.

For example:

const s = "Hello Archetype World!";
const e = slice(s, 6, 9) ? the : ""; /* e is "Archetype" */
const b = 0x48656c6c6f2041726368657479706520576f726c64;
const c = slice(b, 12, 18); /* c is some(0x417263686574797065) */
const f = slice(b, 30, 40); /* f is none */

Parameters


s :

T

Sequence to slice, T must be either:


o :

Offset to start sub sequence


l :

Length of sub sequence

Returns


  • none if a problem occured (offset + length out of bounds)
  • some(v), v being the value of sub sequence

Fails with

does not fail


Michelson


Related

some(v : T)

Optional some value for type option<T>.

Parameter


v :

T

Some value

Returns


Optional value of v

Fails with

does not fail


Michelson


Related

split_ticket(t : ticket<T>, n1 : nat, n2 : nat)

Splits ticket in two new tickets.

Parameters


Ticket to split


n1 :

Amount of first created ticket


n2 :

Amount of second created ticket

Returns


option<ticket<T> * ticket<T>>

Option of pair of created tickets, respectively with n1 and n2 values.

Fails with

does not fail


Michelson


Related

sub_mutez(a : tez, b : tez)

Subtracts a to b and returns an option of tez value.

Parameters


a :

Left-hand side operand to subtract


b :

Right-hand side operand to subtract

Returns


  • none if a - b is negative
  • some(v), if a - b is positive, with v = a - b

Fails with

does not fail


Michelson


Related

sub_nat(a : nat, b : nat)

Subtracts a to b and returns an option of nat value.

Parameters


a :

Left-hand side operand to subtract


b :

Right-hand side operand to subtract

Returns


option<nat>

Option of nat value:
  • some of a - b when a >= b
  • none otherwise

Fails with

does not fail


Related

T U

unpack<T>(b : bytes)

Deserializes a value of type bytes into the corresponding value of type option<T>.

For example, suppose p is a bytes value:

const v ?= unpack<nat>(p) : "UNPACK_FAILED";
/* v is typed nat */

Parameter


b :

Bytes to unpack

Returns


  • none when b is unpackable of type T
  • some(v) v being the value returned by unpacking process

Fails with

does not fail


Michelson


Related

update(m : map<K, V>, k : K, v : option<T>)

Adds or removes value v from associated to key k in map m:
  • none removes key k
  • some(v), adds key k with value v

Parameters


k :

K

Key to add/remove


Optional value to associate to k

Returns


Copy of map m where k is associated to

Fails with

does not fail


Michelson


Related

update(s : set<T>, e : T, b : bool)

Adds or removes element e in set s:
  • removes e when b is false
  • adds e when b is true

Parameters


s :

Set to add or remove element from


e :

T

element to add/remove


b :

Optional value to decide to add or remove

Returns


Copy of set s with element e added or removed.

Fails with

does not fail


Related

V W

voting_power(k : key_hash)

Gets the voting power from a key_hash value.

Parameter


Value to get the voting power of

Returns


Voting power

Fails with

does not fail


Michelson


Related