Michelson Reference

This is a reference to the Michelson language used for smart contract
programming for the Tezos blockchain. It contains a reference to the
types and instructions of the language.
The examples used throughout the reference can be executed in the
browser using the Try Michelson
interpreter. Just click "try it!" in the upper-right corner of the
example to load it in the interpeter:

A well-typed Michelson program implements a function which transforms a pair of Michelson
values representing the transaction parameter and the contract storage, and
returns a pair containing a list of internal operations and the new storage.
Some Michelson instructions make implicit use of data from an execution
environment, derived from the current state of the blockchain (the context),
from the transaction that triggered the contract, and from the block
containing this transaction. These instructions are categorized under
blockchain operations.

Instructions refer to Michelson primitives such as ADD.
Not to be confused with operations.

Operation

The final stack after a contract execution is a pair containing a new storage and a list of operations.
An operation is either a transfer, an account creation or a delegation.

Numerical type

Refers to any of the numerical types of Michelson:
int,
nat,
timestamp or
mutez.
Numerical values are values of one these types.

Sequence type

Refers to any of the two sequence types of Michelson: string or bytes.

Structural type

Refers to any of the structural types of Michelson:
list,
set,
map or
big_map.
Structural values are values of one these types.

Argument

Michelson instructions may be indexed by arguments.
For instance, the
arguments of PUSH nat 3 are nat and 3.
The argument of DIP 2 is 2.
Not to be confused with operands and parameters.

Operand

Refers to stack values consumed by instructions.
Not to be confused with arguments and parameters.

Parameter

Parameter may refer to three things.
First, each contract has a parameter type and when called, takes a parameter value of this type.
Second, some Michelson data types, such as list are parametric.
For instance, a list of integer list nat is an instance of the list type with
the type parameter instantiated to nat.
Finally, the input type of a lambda.
Not to be confused with arguments and operands.

Return value

Refers either to the stack values produced by an instruction, or the return value of a lambda.

Transaction

The execution of a contract is triggered by a blockchain operation
called a transaction, which is part of a block. A transaction has parameters
which are made available to the contracts in two different ways. The
argument of the transaction (a Michelson value) is passed to the contract as
the right side of a pair value, the only element in the initial stack.
Other parameters of the transaction (such as its amount, the implicit account
or contract that triggered it), and data from the block containing the
transaction (its timestamp) can be accessed by specific instructions.

Context

The context is a value representing the state of the blockchain after
the application of an operation. A contract execution may access data from the
context over which the execution is triggered. It has access to the
previous storage of the contract as the left side of a pair value, the only
element in the initial stack. Besides, some instructions use or extract
information from the context (current contract balance, contracts type).

Storage

The storage of a contract is a Michelson value that represents it state.
Initial storage is provided at contract deployement (a.k.a. origination).
Subsequently, transactions trigger contract execution, in which a new store
is computed, based notably on the previous storage and the transaction argument.

Michelson data types (and by extension, the values of each type) can
be characterized by the following type attributes:

Comparable

Comparable values can be stored in sets, can be passed as argument to COMPARE, etc.

Passable

Passable types are those that can be taken as a parameter in contracts.

Storable

Storable types can be used as a storage in contracts.

Pushable

Literal values of pushable types can be given as parameter to the PUSH primitive.

Packable

Values of packable types can be given as serialized using the PACK primitive.

big_map value

These are types that be used in the domain of big_maps.

The attributes of each type is given in the table above. All pushable
types are also packable and vice versa. Except for the domain
specific types operation, contract and big_map, all types are
passable, storable, pushable, packable and can be used as values in
big_maps.

A lazily deserialized map from kty to vty

Description

Lazily deserialized maps from keys of type kty of values of
type vty that we note { Elt key value ; ... }, with keys
sorted. These maps should be used if you intend to store large
amounts of data in a map. Operations on big_maps have
higher gas costs than those over standard maps, as data is
lazily deserialized. However, a big_map has a lower
storage cost than a standard map of the same size.

The behavior of GET, UPDATE and MEM is the same on
big_maps as on standard maps, except that under
the hood, elements are loaded and deserialized on demand.

Literal big_maps cannot be pushed directly in contract
code. Instead, they must be created using EMPTY_BIG_MAP and
manipulated using GET, UPDATE and MEM. However,
literal big_maps are used when originating and calling
contracts using tezos-client.

A sequence of bytes

A chain identifier

Description

An identifier for a chain, used to distinguish the test and the
main chains.

The value is derived from the genesis block hash and will thus
be different on the main chains of different networks and on the
test chains for which the value depends on the first block of the
testchain.

Address of a contract, where type is the contract's parameter type

Description

A value of type contract t is guaranteed to be a valid, existing account whose parameter type is t. This can be opposed to the address type, that merely gives the guarantee that the value has the form of a Tezos address.
Values of the contract type cannot be stored. There are not literal values of type contract. Instead, such values are created using instructions such as CONTRACT or IMPLICIT_ACCOUNT.

A lambda with given parameter and return types

A single, immutable, homogeneous linked list

Description

A single, immutable, homogeneous linked list, whose elements are
of type type, and that we note {} for the empty list or
{ first ; ... }. In the semantics, we use the less-than and
greater-than sign (< and >) to denote a subsequence of
elements. For instance { head ; <tail> }.

A string of characters

Description

The current version of Michelson restricts strings to be the printable
subset of 7-bit ASCII, namely characters with codes from within
[32, 126] range, plus the following escape characters \n,
\\, \". Unescaped line breaks (both \n and \r)
cannot appear in a string.

Add two numerical values

Adds numerical values.
This instruction is polymorphic and accepts any combination of natural numbers and integers as operands.
The return value is a natural number if both operands are natural. Otherwise, it is an integer.

Furthermore, integers can be added to timestamps in which case
the return value is a timestamp offset with the integer number
of seconds.

Finally, a mutez can be added to a mutez, in which case the return value is a mutez.

Boolean and bitwise AND

The instruction AND is defined on boolean and natural number operands.
In the former case, the result is the logical AND of the operands.
In the latter case, the result is the bitwise AND of the operands.

Partially apply a tuplified function from the stack

Partially apply a tuplified function from the stack. That is,
the APPLY instruction consumes a value d of type ty1
and a value i of type lambda (Pair ty1 ty2) ty3.
It partially applies the lambda to d, hence producing a
new lambda of type lambda ty2 ty3 on the stack.
Intuitively, this amounts to creating a new function that acts
like i but with the first parameter fixed to d.

The new lambda is storable, and thus values that cannot be
stored (values of type operation, contract _ and big
map _ _) cannot be captured by APPLY (cannot appear in
ty1).

Push the chain identifier

This instruction pushes on the stack the identifier of the chain
on which the smart contract is executed.

The chain identifier is designed to prevent replay attacks
between the main chain and the test chain forked during amendement
exploration, where contract addresses and storages are identical.

The value is derived from the genesis block hash and will thus
be different on the main chains of different networks and on the
test chains on which the value depends on the first block of the
testchain.

Verifies that a byte sequence has been signed with a given key.
This instruction consumes three operands: a key, a signature and a
byte sequence. It pushes True if and only if the signature is a
valid signature of the byte sequence by the given key.

If called with the initial
storage (Pair "edsigu3QszDjUpeqYqbvhyRxMpVFamEnvm9FYnt7YiiNt9nmjYfh8ZTbsybZ5WnBkhA7zfHsRVyuTnRsGLR6fNHt1Up1FxgyRtF" "hello") and the
parameter "edpkuBknW28nW72KG6RoHtYW7p12T6GKc7nAbwYX5m8Wd9sDVC9yav" then the final storage
will be (Pair "edsigu3QszDjUpeqYqbvhyRxMpVFamEnvm9FYnt7YiiNt9nmjYfh8ZTbsybZ5WnBkhA7zfHsRVyuTnRsGLR6fNHt1Up1FxgyRtF" "hello").

Compare two values

Comparison only works on a class of types that we call
comparable. The COMPARE instruction is defined in an ad hoc way
for each comparable type, but the result of COMPARE is
always an int, which can in turn be checked in a generic
manner using the EQ, NEQ, LT, GT, LE and
GE combinators.

The result of COMPARE is 0 if the top two elements of
the stack are equal, negative if the first element in the stack
is less than the second, and positive otherwise.

Cast an address to a typed contract

Casts from an address to a typed contract ty. If and
only if the address is a valid Tezos contract address with the
type ty, then the result Some contract is pushed. If
the address belongs to an implicit contract, then the type
parameter ty must be unit.If any of these conditions are
not fulfilled, None is pushed.

When this contract is called by anyone except itself, it
originates a new contract with three entrypoints: add,
sub and default and saves its address in its
storage. It then emits a transaction to itself.

When the contract receives a transaction from itself, it
verifies that the stored address can be converted to a
contract for each of the entrypoints add, sub and
default with the respective types nat, nat and
unit using the CONTRACT instruction annotated with the
respective entrypoint. It verifies that the entrypoint
default has the type unit, and that this is equivalent
to to using CONTRACT with no entrypoint annotation. It
also emits transactions to these entrypoints.

Push a contract creation operation

Push a contract creation operation (an origination) based on a
literal. The operands are the optional delegate, the initial
amount taken from the currently executed contract, and the
initial storage of the originated contract. The contract
address is also returned as a first class value (to be dropped,
passed as parameter or stored).

The CONTRACT 'p instruction applied to this resulting
address will fail until the contract is actually originated,
that is, after the generated operation is applied.
It follows that a contract cannot directly return a list of
operations that creates a contract, and call it immediately
after.
However, a contract A creating a contract B will get its
address, so it can return a list of operations that first originates the
contract B, and then calls a contract which in turns calls B: B's address
being either stored in A's storage or passed as parameter, the
executions following B's origination can use CONTRACT 'p on
B's address in order to call it.

Retrieve the nth element of the stack

DIG n consumes a stack that contains at least n
elements. It moves the nth element of the stack to the
top of the stack. The element on top of the stack
is the 0th element, so that DIG 0 is a no-op.
In other words, DIG transforms a stack on the form x0 : x1 :
... : xn : ... into the stack xn : x0 : x1 : ....

Drop the top n elements of the stack

Insert the top element at depth n

DUG n consumes a stack that contains at least n
elements. It removes the top element of the stack, and inserts
it at the nth level in the stack. The element on top of
the stack is at depth 0 so that DUG 0 is a no-op. In
other words, DUG transforms a stack on the form x0 : x1 :
... : xn : ... into the stack x0 : x1 : ... : x0 : xn :
....

Explicitly abort the current program

This instruction aborts the current program exposing the top element of the stack in its error message. It makes the output useless since all subsequent instructions will simply ignore their usual semantics to propagate the failure up to the main result. Its type is thus completely generic.

Create an implicit account

Push on the stack the contract value corresponding to the
implicit account
of a public key hash. These contracts always
have type unit. There is no need to "create" implicit
accounts before referring to them.

Convert a natural number to an integer

Convert a non-negative integer to a natural number

The ISNAT instruction consumes an integer i and returns
a value of type option nat. If the integer is non-negative,
Some n is returned, where n is equal to i but
represented as a natural number. Otherwise, None is
returned.

Consume a structure by applying the body expression to each of its
elements:

In the case of a list or set of elements of type ty1, the body is applied to each
element, and must thus have the type ty1 : A => A.

In the case of a map of keys of type ty1 and values of type ty2, the body is
applied to each binding key to value val in the form of a pair Pair key
val. Thus, the body must have the type Pair ty1 ty2 : A => A.

In each case, the body has access to and can modify the underlying stack.

Wrap a value in a union (left case)

A generic loop

The instruction LOOP consumes a stack b : S of type
bool : A, i.e. where b is boolean and the rest of the
stack is of any type A. The body of the loop, code, is
executed as long as b is True. The body has access to the stack S
but must produce a stack of type bool : A. If b is
False, then the loop is terminated with the resulting stack S.

Update a structure by applying the body expression to each
of its elements:

In the case of a list of elements of type ty1, the body is applied to each
element, and must thus have the type ty1 : A => A.

In the case of a map of keys of type ty1 and values of type ty2, the body is
applied to each binding key to value val in the form of a pair Pair key
val. Thus, the body must have the type Pair ty1 ty2 : A => A.

In each case, the body has access to and can modify the
underlying stack.

Boolean negation and bitwise complement

For numerical values, it returns the two's
complement as
an int. The return type is int and not nat because the sign is
also negated. For instance, the boolean negation of 0 is -1. To
get a natural back, a possibility is to use AND with an unsigned
mask afterwards.

Boolean and bitwise OR

The instruction OR is defined on boolean and natural number operands.
In the former case, the result is the logical OR of the operands.
In the latter case, the result is the bitwise OR of the operands.

If called with the initial
storage Unit and the
parameter (Pair (Pair (Pair "toto" {3;7;9;1}) {1;2;3}) 0x05070707070100000004746f746f020000000800030007000900010200000006000100020003) then the final storage
will be Unit.

This contract has two entrypoints: have_fun and
default. The default entrypoint emits a transfer
token operation that calls back the contract itself, at the
have_fun entrypoint, passing a big_map as
parameter. The have_fun entrypoint unthankfully drops
the received big_map.

parameter(or(or(nat%A)(bool%B))(or%maybe_C(unit%default)(string%C)));storageunit;code{DROP;SELF;DROP;# Refers to entrypoint A of the current contract.SELF%A;DROP;# Refers to the default entry of the current contractSELF%default;PACK;# "SELF" w/o annotation also refers to the default# entry of the current contract. Internally, they are equal.SELF;PACK;ASSERT_CMPEQ;# The following instruction would not typecheck:# SELF %D,# since there is no entrypoint D.UNIT;NILoperation;PAIR;}

parameter(or(or(nat%A)(bool%B))(or%maybe_C(unit%Z)(string%C)));storageunit;code{DROP;# Refers to entrypoint A of the current contract.SELF%A;PACK@Apacked;# Refers to the default entry of the current contractSELF%default;PACK@defpacked;DUP;DIP{SWAP};ASSERT_CMPNEQ;# "SELF" w/o annotation also refers to the default# entry of the current contractSELF;PACK@selfpacked;ASSERT_CMPEQ;# Verify the types of the different entrypoints. CAST is noop# if its argument is convertible with the type of the top of# the stack. is converSELF%A;CAST(contractnat);DROP;SELF%B;CAST(contractbool);DROP;SELF%maybe_C;CAST(contract(or(unit)(string)));DROP;SELF%Z;CAST(contractunit);DROP;SELF;CAST(contract(or(or(nat%A)(bool%B))(or%maybe_C(unit%Z)(string%C))));DROP;SELF%default;CAST(contract(or(or(nat%A)(bool%B))(or%maybe_C(unit%Z)(string%C))));DROP;UNIT;NILoperation;PAIR;}

Push the contract that initiated the current internal transaction

Push the contract that initiated the current
internal transaction. It may be the SOURCE, but may
also not if the source sent an order to an intermediate
smart contract, which then called the current contract.

Consider a scenario involving two contracts, receiver and
proxy. The contract proxy, transfers any amount
received in a call to receiver. Assume a third
contract bootstrap2 creates a transaction to the proxy
contract sending 99 ꜩ . Then proxy creates an internal
transaction that calls receiver:

Distinction between ``SOURCE`` and ``SENDER``.

In this scenario, the source of the internal transaction (from
proxy to receiver) is bootstrap2, whereas the sender
of that transaction is the proxy. That is, if SOURCE is
called in receiver, then address of bootstrap2 is
returned. If SENDER is called in receiver, then address
of proxy is returned.

If instead, bootstrap2 calls receiver directly, then
bootstrap2 would be both source and sender.

Push a delegation operation

The SET_DELEGATE is used to add, update or remove a
delegation. It consumes an operand of type option
key_hash.

If the operand is None, then the produced operation will
remove the executing contracts current delegation, if any. If
the operand is Some kh, then the produced operation will
update or add a delegation, from the executing contract to the
implicit account specified by kh.

Obtain a substring or subsequence of a string respectively byte sequence bytes

The SLICE instruction consumes two natural numbers offset and length
and a character sequence (string) or bytes sequence (bytes).

If offset and length are in bounds, i.e.
offset + start < len, then
it returns a substring, respectively subsequence, Some v of
length length starting at offset (where offset 0 denotes
the first element) of the sequence.

If offset and length is out of bounds, i.e.
offset + length >= len (where len is the length
of the sequence), then None is returned.

Push the contract that initiated the current transaction

Push the contract who signed the transaction initiating this
execution. Note that this contract is necessarily an implicit
account since smart contracts can't sign transactions. They can
however emit internal, unsigned, transactions.

Note that since TRANSFER_TOKENS instructions can be chained,
SOURCE and SENDER are not necessarily the same. See
SENDER for a more detailed discussion of this distinction.

Swap the top two elements of the stack

Push a transaction operation

The TRANSFER_TOKENS instruction consumes a value v of type ty1,
an amount a in mutez and a contract c of type contract ty1. It returns
a transfer operation that will send a mutez to the
specified contract c with the parameter v.

Consequently, the parameter value must be consistent with the
parameter type of the contract. In the case the contract is an
implicit account, then the parameter must be of type unit.

Push the unit value onto the stack

Deserialize data, if valid

Deserialize a value of type bytes into the corresponding
Michelson value of type option ty1.
If the top of the stack is not the serialization of a Michelson
value of type ty1, then None is pushed.
Otherwise, Some v is pushed, where v is the deserialized value.

If called with the initial
storage Unit and the
parameter (Pair -1 (Pair 1 (Pair "foobar" (Pair 0x00AABBCC (Pair 1000 (Pair False (Pair "tz1cxcwwnzENRdhe2Kb8ZdTrdNy4bFNyScx5" (Pair "2019-09-09T08:35:33Z""tz1cxcwwnzENRdhe2Kb8ZdTrdNy4bFNyScx5")))))))) then the final storage
will be Unit.

Boolean and bitwise eXclusive OR

The instruction XOR is defined on boolean and natural number operands.
In the former case, the result is the logical XOR of the operands.
In the latter case, the result is the bitwise XOR of the operands.