namillum/docs/scilla/stdlib.md

Bubble Protocol SDK

---
title: The Scilla Standard Library
---

::: {#stdlib} The Scilla standard library contains five libraries:
`BoolUtils.scilla`, `IntUtils.scilla`, `ListUtils.scilla`, `NatUtils.scilla` and
`PairUtils.scilla`. As the names suggests these contracts implement utility
operations for the `Bool`, `IntX`, `List`, `Nat` and `Pair` types, respectively.
:::

To use functions from the standard library in a contract, the relevant library
file must be imported using the `import` declaration. The following code snippet
shows how to import the functions from the `ListUtils` and `IntUtils` libraries:

```ocaml
import ListUtils IntUtils
```

The `import` declaration must occur immediately before the contract\'s own
library declaration, e.g.:

```ocaml
import ListUtils IntUtils

library WalletLib
... (* The declarations of the contract's own library values and functions *)

contract Wallet ( ... )
... (* The transitions and procedures of the contract *)
```

Below, we present the functions defined in each of the library.

## BoolUtils

- `andb : Bool -> Bool -> Bool`: Computes the logical AND of two `Bool` values.
- `orb : Bool -> Bool -> Bool`: Computes the logical OR of two `Bool` values.
- `negb : Bool -> Bool`: Computes the logical negation of a `Bool` value.
- `bool_to_string : Bool -> String`: Transforms a `Bool` value into a `String`
  value. `True` is transformed into `"True"`, and `False` is transformed into
  `"False"`.

## IntUtils

- `intX_eq : IntX -> IntX -> Bool`: Equality operator specialised for each
  `IntX` type.

```ocaml
let int_list_eq = @list_eq Int64 in

let one = Int64 1 in
let two = Int64 2 in
let ten = Int64 10 in
let eleven = Int64 11 in

let nil = Nil {Int64} in
let l1 = Cons {Int64} eleven nil in
let l2 = Cons {Int64} ten l1 in
let l3 = Cons {Int64} two l2 in
let l4 = Cons {Int64} one l3 in

let f = int64_eq in
(* See if [2,10,11] = [1,2,10,11] *)
int_list_eq f l3 l4
```

- `uintX_eq : UintX -> UintX -> Bool`: Equality operator specialised for each
  `UintX` type.
- `intX_lt : IntX -> IntX -> Bool`: Less-than operator specialised for each
  `IntX` type.
- `uintX_lt : UintX -> UintX -> Bool`: Less-than operator specialised for each
  `UintX` type.
- `intX_neq : IntX -> IntX -> Bool`: Not-equal operator specialised for each
  `IntX` type.
- `uintX_neq : UintX -> UintX -> Bool`: Not-equal operator specialised for each
  `UintX` type.
- `intX_le : IntX -> IntX -> Bool`: Less-than-or-equal operator specialised for
  each `IntX` type.
- `uintX_le : UintX -> UintX -> Bool`: Less-than-or-equal operator specialised
  for each `UintX` type.
- `intX_gt : IntX -> IntX -> Bool`: Greater-than operator specialised for each
  `IntX` type.
- `uintX_gt : UintX -> UintX -> Bool`: Greater-than operator specialised for
  each `UintX` type.
- `intX_ge : IntX -> IntX -> Bool`: Greater-than-or-equal operator specialised
  for each `IntX` type.
- `uintX_ge : UintX -> UintX -> Bool`: Greater-than-or-equal operator
  specialised for each `UintX` type.

## ListUtils

- `list_map : ('A -> 'B) -> List 'A -> : List 'B`.

  | Apply `f : 'A -> 'B` to every element of `l : List 'A`, constructing a list
  (of type `List 'B`) of the results.

  ```ocaml
  (* Library *)
  let f =
    fun (a : Int32) =>
      builtin sha256hash a

  (* Contract transition *)
  (* Assume input is the list [ 1 ; 2 ; 3 ] *)
  (* Apply f to all values in input *)
  hash_list_int32 = @list_map Int32 ByStr32;
  hashed_list = hash_list_int32 f input;
  (* hashed_list is now [ sha256hash 1 ; sha256hash 2 ; sha256hash 3 ] *)
  ```

- `list_filter : ('A -> Bool) -> List 'A -> List 'A`.

  | Filter out elements on the list based on the predicate `f : 'A -> Bool`. If
  an element satisfies `f`, it will be in the resultant list, otherwise it is
  removed. The order of the elements is preserved.

  ```ocaml
  (*Library*)
  let f =
    fun (a : Int32) =>
      let ten = Int32 10 in
      builtin lt a ten

  (* Contract transition *)
  (* Assume input is the list [ 1 ; 42 ; 2 ; 11 ; 12 ] *)
  less_ten_int32 = @list_filter Int32;
  less_ten_list = less_ten_int32 f l
  (* less_ten_list is now  [ 1 ; 2 ]*)
  ```

- `list_head : (List 'A) -> (Option 'A)`.

  | Return the head element of a list `l : List 'A` as an optional value. If `l`
  is not empty with the first element `h`, the result is `Some h`. If `l` is
  empty, then the result is `None`.

- `list_tail : (List 'A) -> (Option List 'A)`.

  | Return the tail of a list `l : List 'A` as an optional value. If `l` is a
  non-empty list of the form `Cons h t`, then the result is `Some t`. If `l` is
  empty, then the result is `None`.

- `list_foldl_while : ('B -> 'A -> Option 'B) -> 'B -> List 'A -> 'B`

  | Given a function `f : 'B -> 'A -> Option 'B`, accumulator `z : 'B` and list
  `ls : List 'A` execute a left fold when our given function returns
  `Some x : Option 'B` using `f z x : 'B` or list is empty but in the case of
  `None : Option 'B` terminate early, returning `z`.

```ocaml
(* assume zero = 0, one = 1, negb is in scope and ls = [10,12,9,7]
 given a max and list with elements a_0, a_1, ..., a_m
 find largest n s.t. sum of i from 0 to (n-1) a_i <= max *)
let prefix_step = fun (len_limit : Pair Uint32 Uint32) => fun (x : Uint32) =>
  match len_limit with
  | Pair len limit => let limit_lt_x = builtin lt limit x in
    let x_leq_limit = negb limit_lt_x in
    match x_leq_limit with
    | True => let len_succ = builtin add len one in let l_sub_x = builtin sub limit x in
      let res = Pair {Uint32 Uint32} len_succ l_sub_x in
      Some {(Pair Uint32 Uint32)} res
    | False => None {(Pair Uint32 Uint32)}
    end
  end in
let fold_while = @list_foldl_while Uint32 (Pair Uint32 Uint32) in
let max = Uint32 31 in
let init = Pair {Uint32 Uint32} zero max in
let prefix_length = fold_while prefix_step init ls in
match prefix_length with
| Pair length _ => length
end
```

- `list_append : (List 'A -> List 'A -> List 'A)`.

  | Append the first list to the front of the second list, keeping the order of
  the elements in both lists. Note that `list_append` has linear time complexity
  in the length of the first argument list.

- `list_reverse : (List 'A -> List 'A)`.

  | Return the reverse of the input list. Note that `list_reverse` has linear
  time complexity in the length of the argument list.

- `list_flatten : (List List 'A) -> List 'A`.

  | Construct a list of all the elements in a list of lists. Each element (which
  has type `List 'A`) of the input list (which has type `List List 'A`) are all
  concatenated together, keeping the order of the input list. Note that
  `list_flatten` has linear time complexity in the total number of elements in
  all of the lists.

- `list_length : List 'A -> Uint32`

  | Count the number of elements in a list. Note that `list_length` has linear
  time complexity in the number of elements in the list.

- `list_eq : ('A -> 'A -> Bool) -> List 'A -> List 'A -> Bool`.

  | Compare two lists element by element, using a predicate function
  `f : 'A -> 'A -> Bool`. If `f` returns `True` for every pair of elements, then
  `list_eq` returns `True`. If `f` returns `False` for at least one pair of
  elements, or if the lists have different lengths, then `list_eq` returns
  `False`.

- `list_mem : ('A -> 'A -> Bool) -> 'A -> List 'A -> Bool`.

  | Checks whether an element `a : 'A` is an element in the list `l : List'A`.
  `f : 'A -> 'A -> Bool` should be provided for equality comparison.

  ```ocaml
  (* Library *)
  let f =
    fun (a : Int32) =>
    fun (b : Int32) =>
      builtin eq a b

  (* Contract transition *)
  (* Assume input is the list [ 1 ; 2 ; 3 ; 4 ] *)
  keynumber = Int32 5;
  list_mem_int32 = @list_mem Int32;
  check_result = list_mem_int32 f keynumber input;
  (* check_result is now False *)
  ```

- `list_forall : ('A -> Bool) -> List 'A -> Bool`.

  | Check whether all elements of list `l : List 'A` satisfy the predicate
  `f : 'A -> Bool`. `list_forall` returns `True` if all elements satisfy `f`,
  and `False` if at least one element does not satisfy `f`.

- `list_exists : ('A -> Bool) -> List 'A -> Bool`.

  | Check whether at least one element of list `l : List 'A` satisfies the
  predicate `f : 'A -> Bool`. `list_exists` returns `True` if at least one
  element satisfies `f`, and `False` if none of the elements satisfy `f`.

- `list_sort : ('A -> 'A -> Bool) -> List 'A -> List 'A`.

  | Sort the input list `l : List 'A` using insertion sort. The comparison
  function `flt : 'A -> 'A -> Bool` provided must return `True` if its first
  argument is less than its second argument. `list_sort` has quadratic time
  complexity.

  ```ocaml
  let int_sort = @list_sort Uint64 in

  let flt =
    fun (a : Uint64) =>
    fun (b : Uint64) =>
      builtin lt a b

  let zero = Uint64 0 in
  let one = Uint64 1 in
  let two = Uint64 2 in
  let three = Uint64 3 in
  let four = Uint64 4 in

  (* l6 = [ 3 ; 2 ; 1 ; 2 ; 3 ; 4 ; 2 ] *)
  let l6 =
    let nil = Nil {Uint64} in
    let l0 = Cons {Uint64} two nil in
    let l1 = Cons {Uint64} four l0 in
    let l2 = Cons {Uint64} three l1 in
    let l3 = Cons {Uint64} two l2 in
    let l4 = Cons {Uint64} one l3 in
    let l5 = Cons {Uint64} two l4 in
    Cons {Uint64} three l5

  (* res1 = [ 1 ; 2 ; 2 ; 2 ; 3 ; 3 ; 4 ] *)
  let res1 = int_sort flt l6
  ```

- `list_find : ('A -> Bool) -> List 'A -> Option 'A`.

  | Return the first element in a list `l : List 'A` satisfying the predicate
  `f : 'A -> Bool`. If at least one element in the list satisfies the predicate,
  and the first one of those elements is `x`, then the result is `Some x`. If no
  element satisfies the predicate, the result is `None`.

- `list_zip : List 'A -> List 'B -> List (Pair 'A 'B)`.

  | Combine two lists element by element, resulting in a list of pairs. If the
  lists have different lengths, the trailing elements of the longest list are
  ignored.

- `list_zip_with : ('A -> 'B -> 'C) -> List 'A -> List 'B -> List 'C )`.

  | Combine two lists element by element using a combining function
  `f : 'A -> 'B -> 'C`. The result of `list_zip_with` is a list of the results
  of applying `f` to the elements of the two lists. If the lists have different
  lengths, the trailing elements of the longest list are ignored.

- `list_unzip : List (Pair 'A 'B) -> Pair (List 'A) (List 'B)`.

  | Split a list of pairs into a pair of lists consisting of the elements of the
  pairs of the original list.

- `list_nth : Uint32 -> List 'A -> Option 'A`.

  | Return the element number `n` from a list. If the list has at least `n`
  elements, and the element number `n` is `x`, `list_nth` returns `Some x`. If
  the list has fewer than `n` elements, `list_nth` returns `None`.

## NatUtils

- `nat_prev : Nat -> Option Nat`: Return the Peano number one less than the
  current one. If the current number is `Zero`, the result is `None`. If the
  current number is `Succ x`, then the result is `Some x`.
- `nat_fold_while : ('T -> Nat -> Option 'T) -> 'T -> Nat -> 'T`: Takes
  arguments `f : 'T -> Nat -> Option 'T`, `` z : `T `` and `m : Nat`. This is
  `nat_fold` with early termination. Continues recursing so long as `f` returns
  `Some y` with new accumulator `y`. Once `f` returns `None`, the recursion
  terminates.
- `is_some_zero : Nat -> Bool`: Zero check for Peano numbers.
- `nat_eq : Nat -> Nat -> Bool`: Equality check specialised for the `Nat` type.
- `nat_to_int : Nat -> Uint32`: Convert a Peano number to its equivalent
  `Uint32` integer.
- `uintX_to_nat : UintX -> Nat`: Convert a `UintX` integer to its equivalent
  Peano number. The integer must be small enough to fit into a `Uint32`. If it
  is not, then an overflow error will occur.
- `intX_to_nat : IntX -> Nat`: Convert an `IntX` integer to its equivalent Peano
  number. The integer must be non-negative, and must be small enough to fit into
  a `Uint32`. If it is not, then an underflow or overflow error will occur.

## PairUtils

- `fst : Pair 'A 'B -> 'A`: Extract the first element of a Pair.

```ocaml
let fst_strings = @fst String String in
let nick_name = "toby" in
let dog = "dog" in
let tobias = Pair {String String} nick_name dog in
fst_strings tobias
```

- `snd : Pair 'A 'B -> 'B`: Extract the second element of a Pair.

## Conversions

This library provides conversions b/w Scilla types, particularly between
integers and byte strings.

To enable specifying the encoding of integer arguments to these functions, a
type is defined for endianness.

```ocaml
type IntegerEncoding =
  | LittleEndian
  | BigEndian
```

The functions below, along with their primary result, also return
`next_pos : Uint32` which indicates the position from which any further data
extraction from the input `ByStr` value can proceed. This is useful when
deserializing a byte stream. In other words, `next_pos` indicates where this
function stopped reading bytes from the input byte string.

- `substr_safe : ByStr -> Uint32 -> Uint32 -> Option ByStr` While Scilla
  provides a builtin to extract substrings of byte strings (`ByStr`), it is not
  exception safe. When provided incorrect arguments, it throws exceptions. This
  library function is provided as an exception safe function to extract, from a
  string `s : ByStr`, a substring starting at position `pos : Uint32` and of
  length `len : Uint32`. It returns `Some ByStr` on success and `None` on
  failure.
- `extract_uint32 : IntegerEncoding -> ByStr -> Uint32 -> Option (Pair Uint32 Uint32)`
  Extracts a `Uint32` value from `bs : ByStr`, starting at position
  `pos : Uint32`. On success, `Some extracted_uint32_value next_pos` is
  returned. `None` otherwise.
- `extract_uint64 : IntegerEncoding -> ByStr -> Uint32 -> Option (Pair Uint64 Uint32)`
  Extracts a `Uint64` value from `bs : ByStr`, starting at position
  `pos : Uint32`. On success, `Some extracted_uint64_value next_pos` is
  returned. `None` otherwise.
- `extract_uint128 : IntegerEncoding -> ByStr -> Uint32 -> Option (Pair Uint128 Uint32)`
  Extracts a Uint128 value from `bs : ByStr`, starting at position
  `pos : Uint32`. On success, `Some extracted_uint128_value next_pos` is
  returned. `None` otherwise.
- `extract_uint256 : IntegerEncoding -> ByStr -> Uint32 -> Option (Pair Uint256 Uint32)`
  Extracts a `Uint256` value from `bs : ByStr`, starting at position
  `pos : Uint32`. On success, `Some extracted_uint256_value next_pos` is
  returned. `None` otherwise.
- `extract_bystr1 : ByStr -> Uint32 -> Option (Pair ByStr1 Uint32)` Extracts a
  `ByStr1` value from `bs : ByStr`, starting at position `pos : Uint32`. On
  success, `Some extracted_bystr1_value next_pos` is returned. `None` otherwise.
- `extract_bystr2 : ByStr -> Uint32 -> Option (Pair ByStr2 Uint32)` Extracts a
  `ByStr2` value from `bs : ByStr`, starting at position `pos : Uint32`. On
  success, `Some extracted_bystr2_value next_pos` is returned. `None` otherwise.
- `extract_bystr20 : ByStr -> Uint32 -> Option (Pair ByStr20 Uint32)` Extracts a
  `ByStr2` value from `bs : ByStr`, starting at position `pos : Uint32`. On
  success, `Some extracted_bystr20_value next_pos` is returned. `None`
  otherwise.
- `extract_bystr32 : ByStr -> Uint32 -> Option (Pair ByStr32 Uint32)` Extracts a
  `ByStr2` value from `bs : ByStr`, starting at position `pos : Uint32`. On
  success, `Some extracted_bystr32_value next_pos` is returned. `None`
  otherwise.
- `append_uint32 : IntegerEncoding -> ByStr -> Uint32 -> ByStr` Serialize a
  `Uint32` value (with the specified encoding) and append it to the provided
  `ByStr` and return the result `ByStr`.
- `append_uint64 : IntegerEncoding -> ByStr -> Uint32 -> ByStr` Serialize a
  `Uint64` value (with the specified encoding) and append it to the provided
  `ByStr` and return the result `ByStr`.
- `append_uint128 : IntegerEncoding -> ByStr -> Uint32 -> ByStr` Serialize a
  `Uint128` value (with the specified encoding) and append it to the provided
  `ByStr` and return the result `ByStr`.
- `append_uint256 : IntegerEncoding -> ByStr -> Uint32 -> ByStr` Serialize a
  `Uint256` value (with the specified encoding) and append it to the provided
  `ByStr` and return the result `ByStr`.

## Polynetwork Support Library

This library provides utility functions used in building the Zilliqa Polynetwork
bridge. These functions are migrated from
[Polynetwork\'s ethereum support](https://github.com/polynetwork/eth-contracts/tree/master/contracts/core/cross_chain_manager),
with the contract itself separately deployed.