Liquidity Reference¶

Contract Format¶

All the contracts have the following form:

[%%version 2.1]

<... local declarations ...>

type storage = TYPE

let%init storage
    (x : TYPE)
    (y : TYPE)
    ... =
    BODY

let%entry entrypoint1
    (p1 : TYPE)
    (s1 : TYPE) =
    BODY

let%entry entrypoint2
    (p2 : TYPE)
    (s2 : TYPE) =
    BODY

let%entry default
    (parameter : TYPE)
    (storage : TYPE) =
    BODY

let%view view1
    (parameter : TYPE)
    (storage : TYPE)
    : TYPE =
    BODY

 ...

The optional version statement tells the compiler in which version of Liquidity the contract is written. The compiler will reject any contract that has a version that it does not understand (too old, more recent).

A contract is composed of type declarations, local values definitions, an initializer, and a set of entry points and views. The type storage must be defined for all contracts.

Each entry point is a special function declared with the keyword let%entry. An entry point must have two arguments, the first one being the parameter (whose type can be inferred, but we recommend writing a type annotation for documentation purposes) and the second one is the storage. The return type of the function can be specified but is not necessary. Each entry point and view must be given a unique name within the same contract.

If there is an entry point named default, it will be the default entry point for the contract, i.e. the one that is called when the entry point is not specified in Contract.call. It is generally a good idea to make this entry point take a parameter of type unit, so that the code will be executed by any transfer made to it without arguments. (This can code to prevent accidental token transfers for instance.)

An entry point always returns a pair (operations, storage), where operations is a list of internal operations to perform after execution of the contract, and storage is the final state of the contract after the call. The type of the pair must match the type of a pair where the first component is a list of opertations and the second is the type of the storage argument.

Only with Love

Views are effect-less functions that return values (usually by reading the storage) and that are accessible outside the contract. Each view takes a parameter and a storage, and returns a value. We recommend writing the parameter and return types for documentation.

<... local declarations ...> is an optional set of type, function and extended primitives declarations. Type declarations can be used to define records and variants (sum-types), described later in this documentation.

An optional initial storage or storage initializer can be given with let%init storage. When deploying a Liquidity contract, if the storage is not constant it is evaluated in the head context.

Note that types, values, entry points and values definitions can be written in any order as long as they are defined before their use (forward references are forbidden).

Basic Types and Values¶

Types in Liquidity are monomorphic. They are all inherited from Michelson, except for algebraic data types and records, that are translated to Michelson types.

Only with love Structured types are kept when compiling to Love.

Basic Types¶

The built-in base types are:

unit: whose only constructor is ()
bool: Booleans
int: Unbounded integers
nat: Unbounded naturals (positive integers)
dun: The type of amounts
string: character strings
bytes: bytes sequences
timestamp: dates and timestamps
key: cryptographic keys
key_hash: hashes of cryptographic keys
signature: cryptographic signatures
operation: type of operations, can only be constructed
address: abstract type of contract addresses
chain_id: abstract type for chain ids

Composite Types¶

Types can be composed using the following type operators:

tuples: noted t1 * t2, t1 * t2 * t3, etc.
functions: 'a -> 'b is the type of functions from 'a to 'b, equivalent to ('a, 'b) lambda.

and the following predefined combinators:

lists: 'a list is the type of lists of elements in 'a
sets: 'a set is the type of sets of elements in 'a ('a must be a comparable type)
maps: ('key, 'val) map is the type of maps whose keys are of type 'key, a comparable type, and values of type 'val;
big maps: ('key, 'val) big_map is the type of lazily deserialized maps whose keys are of type 'key (a comparable type) and values of type 'val;
contracts: S.instance is the type of contracts (instances) of signature S (see Contract Types and Signatures);

and the predefined algebraic data types:

option type: 'a option = None | Some of 'a
variant type: ('a, 'b) variant = Left of 'a | Right of 'b

Record and variant types must be declared beforehand and are referred to by their names.

User defined types can be parameterized by type variables. See Polymorphism for the specifics and limitations.

Contract Handles and View Types¶

Contracts can either be manipulated (stored, passed as argument to a function or a parameter to another contract) as addresses (this is a representation for an untyped contract, whose signature is unknown) or as typed values. Contracts can be freely converted to one type or the other (the internal representation during execution remains identical, but extra checks are performed when going from an address to a typed contract). These typed values mention only a subset of the contract signature. In fact they must mention only a single entry point or view in the signature, this is why we call them handles (to a specific entry point).

There are two kinds of types for these handles: handles to entry points and handles to views.

Handles to entry points need only mention the type of the parameter as such:

%[handle 'parameter]

Only with love Handles to views must mention the view name, the parameter type and the return type:

%[view (view_name : 'parameter -> 'return)]

These special types can be used anywhere a type is required.

Follow these links for the conversion primitives:

Converting handles addresses : Contract.address.
Converting addresses to entry point handles: [%handle: val%entry : ...] or [%handle C.entry].
Only with love Converting addresses to view handles: [%handle: val%view : ...] or [%view C.view].

Constant Values¶

The unique constructor of type unit is ().

The two Booleans (bool) constants are:

true
false

As in Michelson, there are different types of integers:

int : an unbounded integer, positive or negative, simply written 0, 1, 2, -1, -2, …
nat : an unbounded positive integer, written either with a p suffix (0p, 12p, etc.) or as an integer with a type coercion ( (0 : nat) ).
dun : an unbounded positive float of DUNs, written either with a DUN (or dun) suffix (1.00DUN, etc.) or as a string with type coercion (("1.00" : dun)).

Strings (string) are delimited by the characters " and ".

Bytes (bytes) are sequences of hexadecimal pairs preceeded by 0x, for instance:

0x
0xabcdef

Timestamps (timestamp) are written in ISO 8601 format, like in Michelson:

2015-12-01T10:01:00+01:00

Keys, key hashes and signatures are base58-check encoded, the same as in Michelson:

dn1HieGdCFcT8Lg9jDANfEGbJyt6arqEuSJb is a key hash (key_hash)
edpkuit3FiCUhd6pmqf9ztUTdUs1isMTbF9RBGfwKk1ZrdTmeP9ypN is a public key (key)
edsigedsigthTzJ8X7MPmNeEwybRAvdxS1pupqcM5Mk4uCuyZAe7uEk68YpuGDeViW8wSXMrCi5CwoNgqs8V2w8ayB5dMJzrYCHhD8C7 is a signature (signature)

There are also three types of collections: lists, sets and maps. Constants collections can be created directly:

Lists: ["x"; "y"] for a string list;
Sets: Set [1; 2; 3; 4] for an int set;
Maps: Map [1, "x"; 2, "y"; 3, "z"] for a (int, string) map;
Big maps: BigMap [1, "x"; 2, "y"; 3, "z"] for a (int, string) big_map

Options (option) can be defined with:

An empty option: None
A valued option: Some 3

Variants (variant) can be defined with:

Left alternative: Left "hello"
Right alternative: Right 3

for a (string, int) variant.

The variant type is not supposed to be used by programmers, who can defined their own algebraic data types. Instead, variant is used when decompiling Michelson code.

It is also possible to coerce some constants between their inferred type and another compatible type, using the notation ( CONSTANT : NEWTYPE ):

A string can be coerced to dun (the string must contain an integer in mudun à la Michelson), timestamp, key, address, _ contract, key_hash and signature.
A bytes can be coerced to address, _.instance, key, key_hash and signature.
An constant address can be coerced to a contract handle.
A constant contract handle can be coerced to address.
A key_hash can be coerced to an address and a contract handle (to entry point default of parameter type unit).

Starting with version 0.5, constant values such as [], Map, Set, None do not need to be annotated with their type anymore. It will be inferred (when possible), see Type inference).

Pure (not closures) lambdas are also constants in Liquidity.

For instance fun (x : int) -> x + 1 can be used anywhere that a constant of type int -> int is required.

Predefined Primitives¶

There are two kinds of primitives in the language:

Prefix primitives are used by putting the primitive before the arguments: prim x y z. All alphanumerical primitives are prefix primitives, except lor, lxor, mod, land, lsl, lsr and asr.
Infix primitves are used by putting the primitive between the arguments: x prim y. Infix primitives are always operators (+, -, etc.).

When the type of a primitive is specified, we extend the notation for functions like this:

TYPE_ARG -> TYPE_RESULT for a primitive with one argument
TYPE_ARG1 -> TYPE_ARG2 -> TYPE_RESULT for a primitive with two arguments

Extended Primitives¶

Only with michelson

Additional prefix Michelson primitives can be added to the language through a local declaration as follows:

external prim_name : TYPE1 -> ... -> TYPE_ARG1 -> ... -> TYPE_RESULT = "MINST" FLAGS

Such declaration takes as input an arbitrary number of type arguments (TYPE1 -> ...) of the form [%type: 'a], where 'a is the variable bound to the type.

Then follows an arbitrary (but non-null) number of typed arguments (TYPE_ARG1 -> ...) of the form [%stack: TYPE], where TYPE corresponds to any Michelson type, possibly containing one or more of the type variables introduced previously. Here, %stack means the argument resides on the stack. It is mandatory for all arguments, except when declaring a primitive that takes no argument, in which case it takes a single argument of type unit, without the %stack specifier ([%stack: unit] would instead mean that the primitive takes a unit value from the stack).

The result type (TYPE_RESULT) is specified using the same form as arguments, i.e. [%stack: TYPE], where a bare unit indicates a primitive that does not produce any value on the stack. It is also possible to specify that the primitive returns several values on the stack using a tuple notation : [%stack: TYPE1] * [%stack: TYPE2] * .... In this case, every component of the tuple must have a %stack specifier and will occupy a different stack cell. All the values will be assembled into an actual tuple before being returned to Liquidity.

MINST is the actual Michelson instruction to generate and will be written as-is in the output file, followed by the given type arguments, if any.

FLAGS allows to give additional information about the primitive. Currently, the only supported flag is [@@effect], which specifies that the primitive may have side-effects. This prevents calls to this primitive from being inlined or eliminated when the return value is not used.

A call to an extended primitive is then performed as follows:

prim_name TYPE1 ... ARG1 ...

After the primitive name, a number of type arguments (TYPE1 ...) of the form [%type: TYPE] may be given (if the primitive has been declared to take type arguments), where TYPE is any Michelson type. Then follow the actual arguments (ARG1 ...).

Comparison between values¶

All values are not comparable. Only two values of the following types can be compared with each other:

bool
int
nat
dun
string
bytes
timestamp
key_hash
address

The following comparison operators are available:

= : equal
<> : not-equal
< : strictly less
<= : less or equal
> : strictly greater
>= : greater or equal

There is also a function compare : 'a -> 'a -> int to compare two values and return an integer, as follows. compare x y

returns 0 if x and y are equal
returns a strictly positive integer if x > y
returns a strictly negative integer if x < y

The `Current` module¶

Current.balance: unit -> dun: returns the balance of the current contract. The balance contains the amount of dun that was sent by the current operation.
Try online
```
type storage = dun

let%entry default () s =
  let bal = Current.balance() in
  [], bal
```
Current.time: unit -> timestamp: returns the timestamp of the block in which the transaction is included. This value is chosen by the baker that is including the transaction, so it should not be used as a reliable source of alea.
Try online
```
type storage = timestamp

let%entry default () _ =
  let now = Current.time() in
  [], now
```
Current.amount: unit -> dun: returns the amount of dun transferred by the current operation (standard or internal transaction).
Try online
```
type storage = dun

let%entry default () _ =
  let received = Current.amount () in
  [], received
```
Current.source: unit -> address: returns the address that initiated the current top-level transaction in the blockchain. It is the same one for all the transactions resulting from the top-level transaction, standard and internal. It is the address that paid the fees and storage cost, and signed the operation on the blockchain.
Try online
```
type storage = address

let%entry default () owner =
  let addr = Current.source () in
  if addr <> owner then
    Current.failwith ("Not allowed");
  [], owner
```
Current.sender: unit -> address: returns the address that initiated the current transaction. It is the same as the source for the top-level transaction, but it is the originating contract for internal operations.
Try online
```
type storage = address

let%entry default () owner =
  let addr = Current.sender () in
  if addr <> owner then
    Current.failwith ("Sender cannot call");
  [], owner
```
failwith or Current.failwith: 'a -> 'b: makes the current transaction and all its internal transactions fail. No modification is done to the context. The argument can be any value (often a string and some argument), the system will display it to explain why the transaction failed.
Try online
```
type storage = unit

let%entry default (param : string) _ =
  if String.length param > 256p then
    Current.failwith ("Parameter too long", param);
  [], ()
```

Current.block_level: unit -> nat: returns the level of the block in which the transaction is included.

Liquidity Reference¶

Contract Format¶

Basic Types and Values¶

Basic Types¶

Composite Types¶

Contract Handles and View Types¶

Constant Values¶

Predefined Primitives¶

Extended Primitives¶

Comparison between values¶

The Current module¶

Operations on tuples¶

Operations on numeric values¶

Operations on contracts¶

Cryptographic operations¶

Operations on bytes¶

Operations on strings¶

Operations on lambdas¶

Operations on lists¶

Operations on sets¶

Operations on maps¶

Operations on Big maps¶

Operations on generic collections¶

The Modules and Contracts System¶

Module and Contract Aliases¶

First Class Contract Structures¶

Toplevel Contracts¶

Contract Types and Signatures¶

Predefined Contract Signatures¶

Type inference and Polymorphism¶

Type inference¶

Polymorphism¶

ReasonML Syntax¶

ReasonML Compiler Arguments¶

ReasonML Syntax Extensions¶

The `Current` module¶