Scilla

https://github.com/zilliqa/scilla
Admin
Scilla - A Smart Contract Intermediate Level Language
Tokens:15,890
Snippets:130
Trust Score:9.5
License:GPL-3.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install OCaml Development Environment Setup

Source: https://github.com/zilliqa/scilla/blob/master/CONTRIBUTING.md

This command uses 'opam' to install 'opam-user-setup', which helps in configuring a basic OCaml development environment. It can install useful extensions like 'tuareg', 'merlin', and 'ocp-indent' for enhanced development experience.

```Shell
opam install user-setup
```

--------------------------------

### Install Scilla Dependencies with Homebrew on macOS

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Installs all dependencies listed in the project's Brewfile using Homebrew's bundle command, streamlining the setup process for Scilla on macOS.

```shell
brew bundle
```

--------------------------------

### Install Core Scilla Dependencies via APT

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Installs essential build tools and libraries required for compiling and running Scilla, including OCaml, curl, build-essential, and various development headers.

```shell
sudo apt-get install -y curl build-essential m4 ocaml pkg-config zlib1g-dev libgmp-dev libffi-dev libssl-dev libboost-system-dev libpcre3-dev
```

--------------------------------

### Install Scilla Dependencies from Project Directory (Alternative)

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Navigates to the Scilla project directory and installs its OCaml dependencies defined in `scilla.opam`, including test dependencies, as an alternative method.

```shell
cd PROJECT_DIR    # go inside your Scilla project directory
opam install ./scilla.opam --deps-only --with-test
```

--------------------------------

### Initialize OPAM for Fresh Installation

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Initializes the OPAM environment, specifying OCaml compiler version 4.12.0, suitable for a fresh OPAM setup where sandboxing might not be a concern.

```shell
opam init --compiler=ocaml-base-compiler.4.12.0 --yes
```

--------------------------------

### Install Scilla Dependencies into Global Opam Switch

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

After creating a global opam switch, these commands install Scilla's specific dependencies. First, `SCILLA_REPO_ROOT` is set to the path of the Scilla repository. Then, `opam install` is used with the `scilla.opam` file to install only the required dependencies (`--deps-only`), including those for testing (`--with-test`), into the currently active global switch.

```shell
export SCILLA_REPO_ROOT=/path/to/scilla
opam install ./scilla.opam --deps-only --with-test
```

--------------------------------

### Install OPAM 2.x via Official Script

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Downloads and executes the official OPAM 2.x installation script from GitHub, ensuring the correct version is installed for WSL compatibility, as older versions may not work.

```shell
sh <(curl -sL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)
```

--------------------------------

### Install Scilla Dependencies from Local OPAM File

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Navigates to the Scilla project directory and installs its OCaml dependencies defined in `scilla.opam`, including test dependencies, using OPAM.

```shell
cd <path/to/unzipped/latest/scilla/release>
opam install ./scilla.opam --deps-only --with-test
```

--------------------------------

### Install and Configure vcpkg for Scilla

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Provides shell commands to clone, bootstrap, and configure vcpkg, then sets the necessary environment variables (VCPKG_ROOT and PKG_CONFIG_PATH) to integrate vcpkg with the Scilla build process.

```shell
$ git clone https://github.com/Microsoft/vcpkg.git /path/to/vcpkg
$ cd /path/to/vcpkg && git checkout 2022.09.27 && ./bootstrap-vcpkg.sh
$ cd /path/to/scilla
$ export VCPKG_ROOT=/path/to/vcpkg
$ export PKG_CONFIG_PATH="$(pwd)/vcpkg_installed/$(scripts/vcpkg_triplet.sh)/lib/pkgconfig:$PKG_CONFIG_PATH"
```

--------------------------------

### Install Scilla from Local Repository using opam

Source: https://github.com/zilliqa/scilla/blob/master/README.md

Steps to install Scilla from a local clone of its repository into the opam switch, ensuring the correct git branch is active for pinning.

```shell
cd <scilla-repo>
git checkout master
opam install ./scilla.opam
```

--------------------------------

### Install Scilla Dependencies via Make Target

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Executes a Makefile target (`opamdep`) to install Scilla's OCaml dependencies, providing a convenient alternative to direct `opam install` commands.

```shell
make opamdep
```

--------------------------------

### Example Output of OPAM Depext Check

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Illustrates the expected output from `opam depext`, listing detected system packages and confirming their presence, indicating successful dependency resolution.

```text
# Detecting depexts using vars: arch=x86_64, os=macos, os-distribution=homebrew, os-family=homebrew
# The following system packages are needed:
gcc
gmp
libffi
lzlib
pcre
pkg-config
# All required OS packages found.
```

--------------------------------

### Example Scilla Runner Command Line Execution

Source: https://github.com/zilliqa/scilla/wiki/Scilla-Server-API

Illustrates a typical command-line invocation of the `scilla-runner` executable. It shows how to specify input files (initial state, message, blockchain), output files, the contract source, and library directories, along with a gas limit.

```Bash
./bin/scilla-runner -init tests/runner/helloWorld/init.json -istate tests/runner/helloWorld/state_1.json -o output_1.json -imessage tests/runner/helloWorld/message_1.json -iblockchain tests/runner/helloWorld/blockchain_1.json -i tests/contracts/helloWorld.scilla -libdir src/stdlib “-gaslimit 800
```

--------------------------------

### Build Scilla Project

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Cleans previous build artifacts and then compiles the Scilla project using its Makefile, preparing the binaries for installation or testing.

```shell
make clean; make
```

--------------------------------

### Install Scilla Binaries to OPAM Switch

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Installs the compiled Scilla binaries into the active OPAM switch, making them globally accessible within that specific OPAM environment.

```shell
make install
```

--------------------------------

### Install Scilla Dependencies on Ubuntu

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Adds the OPAM PPA, updates package lists, and installs essential build tools and libraries for Scilla on Ubuntu using apt-get, including curl, build-essential, m4, ocaml, opam, pkg-config, and various development libraries.

```shell
sudo add-apt-repository -y ppa:avsm/ppa
sudo apt-get update
sudo apt-get install -y curl build-essential m4 ocaml opam pkg-config zlib1g-dev libgmp-dev libffi-dev libssl-dev libboost-system-dev libboost-test-dev libpcre3-dev cmake autoconf patchelf
```

--------------------------------

### Test Scilla Installation with Eval Runner

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Executes a Scilla test file using `eval-runner` with a specified gas limit and library directory to verify the successful installation and functionality of Scilla.

```shell
eval-runner -gaslimit 10000 -libdir src/stdlib tests/eval/good/let.scilexp
```

--------------------------------

### Install Scilla Dependencies on openSUSE

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Installs required system packages for building Scilla on openSUSE using the zypper package manager, including development libraries for curl, m4, opam2, pkg-config, zlib, gmp, libffi, openssl, and boost.

```shell
sudo zypper install -y curl m4 opam2 pkg-config zlib-devel gmp-devel libffi-devel libopenssl-devel boost-devel
```

--------------------------------

### Install and Uninstall Scilla with Make

Source: https://github.com/zilliqa/scilla/blob/master/README.md

Commands to install Scilla into your opam switch and to subsequently uninstall it, managing its presence in your OCaml environment.

```shell
make install
```

```shell
make uninstall
```

--------------------------------

### Install Scilla Development Version via opam from GitHub

Source: https://github.com/zilliqa/scilla/blob/master/README.md

Command to install the latest development version of the Scilla package directly from its GitHub repository into your opam switch.

```shell
opam pin add scilla git+https://github.com/Zilliqa/scilla#master --yes
```

--------------------------------

### Set Up Current Shell for OPAM Environment

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Evaluates the OPAM environment variables in the current shell, making OPAM commands and installed packages available for immediate use.

```shell
eval $(opam env)
```

--------------------------------

### Example `_extlibs` Entry in Scilla `init.json`

Source: https://github.com/zilliqa/scilla/wiki/Library-import-mechanism-in-Scilla

This JSON snippet illustrates the structure of an `_extlibs` entry within an `init.json` file. When provided to `scilla-runner` or `scilla-checker`, this entry maps a library name (e.g., 'Foo') to its deployed address, allowing Scilla to locate and load the corresponding `.scillib` file from the specified `-libdir` path. It facilitates explicit library linking during development or deployment.

```javascript
{
      "vname" : "_extlibs",
      "type" : "List(Pair String ByStr20)",
      "value" : [
          {
              "constructor" : "Pair",
              "argtypes" : ["String", "ByStr20"],
              "arguments" : ["Foo", "0x986556789012345678901234567890123456abcd"]
          },
          ...
      ]
    }
```

--------------------------------

### Check System-Level OPAM Dependencies

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Commands to check and ensure all necessary system-level packages required by OPAM are installed, prompting the user to install any missing ones.

```shell
opam pin add . --no-action --yes
opam depext
opam pin remove scilla
```

--------------------------------

### Create Local OPAM Switch for Scilla

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Creates a new local OPAM switch specifically for the Scilla project, installing OCaml 4.12.0 and its dependencies, including test dependencies, within this isolated environment.

```shell
opam switch create ./ --deps-only --with-test --yes ocaml-base-compiler.4.12.0
```

--------------------------------

### Add OCaml PPA Repository

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Adds the OCaml PPA (Personal Package Archive) repository to the system's apt sources, providing access to newer OCaml packages for installation.

```shell
sudo add-apt-repository -y ppa:avsm/ppa
```

--------------------------------

### Uninstall Scilla Binaries from OPAM Switch

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Removes the Scilla binaries previously installed into the OPAM switch, cleaning up the installation.

```shell
make uninstall
```

--------------------------------

### Interact with Scilla Server using scilla-client

Source: https://github.com/zilliqa/scilla/blob/master/README.md

Shows how to use `scilla-client` to interact with a running `scilla-server` instance. Examples include running a contract transition and checking a contract for syntax and type errors, passing arguments similar to `scilla-runner` and `scilla-checker`.

```Shell
scilla-client run -argv " -init tests/runner/crowdfunding/init.json -istate tests/runner/crowdfunding/state_4.json -iblockchain tests/runner/crowdfunding/blockchain_4.json -imessage tests/runner/crowdfunding/message_4.json -o tests/runner/crowdfunding/output_4.json -i tests/contracts/crowdfunding.scilla -libdir src/stdlib -gaslimit 8000"
```

```Shell
scilla-client check -argv " -libdir src/stdlib -gaslimit 8000 tests/contracts/helloWorld.scilla"
```

--------------------------------

### Reinstall Core Scilla Dependencies with Fix-Missing

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Reinstalls essential build tools and libraries, using the `--fix-missing` flag to resolve any broken dependencies or incomplete installations from previous attempts.

```shell
sudo apt-get install -y curl build-essential m4 ocaml pkg-config zlib1g-dev libgmp-dev libffi-dev libssl-dev libboost-system-dev libpcre3-dev --fix-missing
```

--------------------------------

### Run Zilliqa State Conversion Tool with Example Inputs

Source: https://github.com/zilliqa/scilla/blob/master/scripts/StateJsonConvert/README.md

This command executes the `convert.exe` tool to transform Zilliqa API state JSON into the Scilla-compatible format. It takes the Zilliqa API state JSON file via the `-s` option and the `scilla-checker` contract information JSON file via the `-c` option as required inputs.

```Shell
./convert.exe -s tests/ZilSwap/state.json -c tests/ZilSwap/contractinfo.json
```

--------------------------------

### Create Local Opam Switch for Scilla Dependencies

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

This command creates a local opam switch in the current directory (which should be the project root). It installs only the dependencies (`--deps-only`) required for Scilla, including those for testing (`--with-test`), using the specified OCaml base compiler version. This approach helps prevent dependency conflicts with other OCaml projects.

```shell
opam switch create ./ --deps-only --with-test --yes ocaml-base-compiler.4.12.0
```

--------------------------------

### Build Conversion Tool Executable

Source: https://github.com/zilliqa/scilla/blob/master/scripts/StateJsonConvert/README.md

This command compiles the conversion tool executable named `convert.exe`. Successful compilation requires the prior installation of `libjsoncpp-dev` and `libboost-program-options-dev` system packages.

```Shell
make
```

--------------------------------

### Set PKG_CONFIG_PATH for OpenSSL

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Sets the PKG_CONFIG_PATH environment variable to include the OpenSSL prefix, which is necessary if OpenSSL is installed in a non-default location.

```shell
export PKG_CONFIG_PATH="_OpenSSL_prefix_/lib/pkgconfig:$PKG_CONFIG_PATH"
```

--------------------------------

### Using Scilla Standard Library with opam

Source: https://github.com/zilliqa/scilla/wiki/Stdlib

This snippet demonstrates how to invoke the `scilla-checker` tool to compile a Scilla contract (`foo.scilla`) while correctly referencing the standard library modules. It uses `opam var scilla:lib` to dynamically locate the Scilla installation's library directory, ensuring the standard library is accessible.

```shell
scilla-checker -gaslimit 10000 -libdir "$(opam var scilla:lib)/stdlib" foo.scilla
```

--------------------------------

### Example JSON Output for Scilla List Int64

Source: https://github.com/zilliqa/scilla/wiki/UI-design-for-inputting-ADT-values

This JSON snippet illustrates the output generated by the `get_input` algorithm for a Scilla `List Int64` containing the elements `[0, 2]`. It demonstrates the nested `constructor`, `argtypes`, and `arguments` structure for ADTs like `Cons` and `Nil`.

```JSON
{
      "constructor": "Cons",
      "argtypes": [
        "Int64"
      ],
      "arguments": [
        "0",
        {
          "constructor": "Cons",
          "argtypes": [
            "Int64"
          ],
          "arguments": [
            "2",
            {
              "constructor": "Nil",
              "argtypes": [
                "Int64"
              ],
              "arguments": []
            }
          ]
        }
      ]
    }
```

--------------------------------

### Profile Scilla Executable with Valgrind Callgrind

Source: https://github.com/zilliqa/scilla/wiki/Profiling-Scilla-:-Tips

Once the Scilla executables are built with debug information, use Valgrind's Callgrind tool to profile their execution. The command `valgrind --tool=callgrind -v ./bin/scilla-runner ...` will generate profiling data, which can then be visualized using tools like KCachegrind. Callgrind samples code execution to identify where most time is spent.

```Shell
valgrind --tool=callgrind -v ./bin/scilla-runner ...
```

--------------------------------

### Configure OCaml Dune for Debug Compilation and Rebuild Scilla

Source: https://github.com/zilliqa/scilla/wiki/Profiling-Scilla-:-Tips

To enable line-level debugging information in the compiled Scilla executables, modify all `dune` files in the `src/` directory recursively. Add the `(ocamlopt_flags -g)` line to these files. After modification, perform a clean build using `make clean; make` to ensure the changes are applied.

```Shell
# Edit dune files recursively in src/ directory
# Add the following line:
(ocamlopt_flags -g)

# Then rebuild from scratch
make clean; make
```

--------------------------------

### Format Scilla Codebase

Source: https://github.com/zilliqa/scilla/blob/master/CONTRIBUTING.md

This command automatically formats the Scilla source code according to the project's style guide. It requires the 'ocamlformat' opam package and will modify files in place to ensure adherence to coding standards.

```Shell
make fmt
```

--------------------------------

### Scilla `nat_fold` Type Instantiation Example

Source: https://github.com/zilliqa/scilla/wiki/Folds

Illustrates how to instantiate the polymorphic `nat_fold` function with specific types in Scilla before it is applied to arguments. This is necessary because folds are polymorphic functions.

```Scilla
  let typed_folder = @nat_fold (Product Int Int) in
  let folder = typed_folder iter_fun init_val in
  (* Using folder as a function of type nat -> (Product Int Int) *)
```

--------------------------------

### Example Zilliqa API Contract State JSON Format

Source: https://github.com/zilliqa/scilla/blob/master/scripts/StateJsonConvert/README.md

This JSON snippet illustrates the typical structure of contract state data returned by the Zilliqa API. It shows how basic variables like `_balance` and complex map structures like `admins` are represented, often without explicit type information.

```JSON
{
  "_balance": "0",
  "admins": {
    "0xdfa89866ae86632b36361d53b76c1373448c28fa": {
      "argtypes": [],
      "arguments": [],
      "constructor": "True"
    }
  }
}
```

--------------------------------

### Example Scilla-Compatible Contract State JSON Format

Source: https://github.com/zilliqa/scilla/blob/master/scripts/StateJsonConvert/README.md

This JSON snippet demonstrates the desired output format for contract state data, which is compatible with Scilla. It includes explicit type information (`type`) for each variable and uses `vname` and `value` fields, showing how complex structures are represented as arrays of key-value pairs.

```JSON
[
  {
    "vname" : "_balance",
    "type" : "Uint128",
    "value" : "0"
  },
  {
    "vname" : "admins",
    "type" : "Map ByStr20 Bool",
    "value" : [
      {
        "key" : "0xdfa89866ae86632b36361d53b76c1373448c28fa",
        "val" : {
          "argtypes": [],
          "arguments": [],
          "constructor": "True"
        }
      }
    ]
  }
]
```

--------------------------------

### C++ Equivalent Member Struct Definition

Source: https://github.com/zilliqa/scilla/blob/master/tests/runner/bookstore/readme.md

This C++ struct defines a `Member` object, serving as an illustrative equivalent for how data might be structured in Scilla for a CRUD application. It includes fields for address, name, and membership type, demonstrating a conceptual approach to object representation in a language like Scilla that lacks direct struct support.

```c++
// c++ equivalent
struct Member {
    ByStr20 addr;
    String name;
    Uint32 membershipType;
}
```

--------------------------------

### Scilla Map Operations

Source: https://github.com/zilliqa/scilla/wiki/Scilla-Built-Ins

Explains built-in functions for interacting with Map data structures in Scilla. Covers insertion (`put`), retrieval (`get`), removal (`remove`), key presence check (`contains`), and conversion of a map to a list of key-value pairs (`to_list`). Maps are essential for storing dynamic data in contracts.

```APIDOC
put m k v: Insert key k and value v into Map m. Returns a new Map.
get m k: In Map m, for key k, return the associated value as Option v. The returned value is None if k is not in the map m.
remove k: Remove key k and it's associated value v from the map. Returns a new updated Map.
contains k: Is key k and it's associated value v present in the map? Returns Bool.
to_list m: Convert Map m into a List (Pair ('A) ('B)) where 'A and 'B are key and value types.
```

--------------------------------

### Git Commands for Release Branch Creation and Alpha Tagging

Source: https://github.com/zilliqa/scilla/wiki/Release-Checklist

This snippet provides a sequence of Git commands to prepare for a new release. It involves checking out the master branch, pulling the latest changes, creating a new release branch from master, pushing this branch to the remote repository, and finally tagging and pushing an alpha release version.

```shell
$git checkout master # Checkout master
$git pull  # Get and merge the latest master from the repo
$git checkout -b release-v3.2.1 master # Create a new release branch
$git push origin release-v3.2.1 # Push the release branch to the repo
$git tag v3.2.1-alpha.0
$git push origin v3.2.1-alpha.0
```

--------------------------------

### Execute Scilla Contract Transition with scilla-runner

Source: https://github.com/zilliqa/scilla/blob/master/README.md

Demonstrates how to execute a Scilla contract transition using the `scilla-runner` command-line tool. It takes initialization, state, blockchain, and message JSON files as input, along with the contract file and library directory, outputting results to a specified file.

```Shell
scilla-runner -init tests/runner/crowdfunding/init.json -istate tests/runner/crowdfunding/state_4.json -iblockchain tests/runner/crowdfunding/blockchain_4.json -imessage tests/runner/crowdfunding/message_4.json -o tests/runner/crowdfunding/output_4.json -i tests/contracts/crowdfunding.scilla -libdir src/stdlib -gaslimit 8000
```

```Shell
scilla-runner -init tests/runner/zil-game/init.json -istate tests/runner/zil-game/state_5.json -iblockchain tests/runner/zil-game/blockchain_5.json -imessage tests/runner/zil-game/message_5.json -o tests/runner/zil-game/output_5.json -i tests/contracts/zil-game.scilla -libdir src/stdlib -gaslimit 8000
```

--------------------------------

### Compile Scilla Client with Makefile

Source: https://github.com/zilliqa/scilla/wiki/Scilla-Server-API

Provides the Makefile configuration to compile `client.cpp` into `client.exe`. It specifies C++14 standard, enables debugging flags (`-ggdb3`), warns about common issues (`-Wall`), and links necessary JSON-RPC client and common libraries (`-ljsoncpp`, `-ljsonrpccpp-client`, `-ljsonrpccpp-common`).

```Make
CFLAGS=-ggdb3 -Wall -std=c++14
LDFLAGS=-ljsoncpp -ljsonrpccpp-client -ljsonrpccpp-common

client.exe : client.cpp
	g++ ${CFLAGS} client.cpp -o client.exe ${LDFLAGS}
```

--------------------------------

### Execute Scilla Client Commands

Source: https://github.com/zilliqa/scilla/wiki/Scilla-Server-API

Demonstrates how to run the compiled `client.exe` to perform `check` and `run` operations against a Scilla server. These commands mimic the functionality of `scilla-runner` and `scilla-checker`, allowing interaction with Scilla contracts.

```bash
client.exe check tests/contracts/wallet_2.scilla -libdir src/stdlib -gaslimit 10000

client.exe run  -init tests/runner/wallet_2/init.json -i tests/contracts/wallet_2.scilla -libdir src/stdlib -o /tmp/output.json -galimit 8000 -imessage tests/runner/wallet_2/message_7.json -iblockchain tests/runner/wallet_2/blockchain_7.json -istate tests/runner/wallet_2/state_7.json
```

--------------------------------

### Initialize OPAM for WSL with Sandboxing Disabled

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Initializes the OPAM environment, disabling sandboxing due to current WSL limitations and specifying the OCaml compiler version 4.12.0 for compatibility.

```shell
opam init --disable-sandboxing --compiler=ocaml-base-compiler.4.12.0 --yes
```

--------------------------------

### JSON-RPC Request for Scilla Server Run Method

Source: https://github.com/zilliqa/scilla/wiki/Scilla-Server-API

Demonstrates how to format a JSON-RPC request to the `scilla-server`'s `run` method. This request encapsulates `scilla-runner` command-line arguments within the `argv` parameter, showing the structure required for server interaction.

```JSON
{
  "jsonrpc": "2.0", 
  "method": "run", 
  "id" : 3, 
  "params": 
  {
    "argv" : ["-init", "tests/runner/helloWorld/init.json", "-istate", "tests/runner/helloWorld/state_1.json", "-o", "output_1.json", "-imessage", "tests/runner/helloWorld/message_1.json", "-iblockchain", "tests/runner/helloWorld/blockchain_1.json", "-i", "tests/contracts/helloWorld.scilla", "-libdir", "src/stdlib", "-gaslimit", "800"]
  }
}
```

--------------------------------

### Run Scilla Contract Simulation with easyrun.sh

Source: https://github.com/zilliqa/scilla/blob/master/README.md

Provides a simplified method to execute Scilla contract simulations using the `easyrun.sh` script. This script automates the process, allowing users to specify the contract name and the number of simulation steps.

```Shell
./easyrun.sh crowdfunding 1
```

--------------------------------

### Shell Commands for Cleaning and Packaging Scilla Release Assets

Source: https://github.com/zilliqa/scilla/wiki/Release-Checklist

These commands are used to clean the Scilla project directory by removing build artifacts and dependencies, and then to create zip and tar.gz archives of the project for release distribution. This process is particularly important for projects with Git submodules, as GitHub does not automatically pack them.

```shell
git clean -dfx; rm -rf _opam _build .git deps/libff/{build,install}
zip scilla-<tag>.zip -r scilla-<tag>
tar cfz scilla-<tag>.tar.gz scilla-<tag>
```

--------------------------------

### Symlink Local opam Switch for Scilla-based Projects

Source: https://github.com/zilliqa/scilla/blob/master/README.md

Instructions on how to create a symbolic link to reuse a local opam switch from the Scilla repository within a separate Scilla-based project.

```shell
cd <scilla-based-project-repo>
ln -s ~/path/to/scilla/_opam _opam
```

--------------------------------

### Compile Scilla Project from Source

Source: https://github.com/zilliqa/scilla/blob/master/README.md

Command to build the Scilla project from its root directory after cloning the source code, compiling all necessary components.

```shell
make
```

--------------------------------

### Clone Scilla Source Code with Submodules

Source: https://github.com/zilliqa/scilla/blob/master/README.md

Instructions to clone the Scilla repository, including all its necessary submodules, for local development and contribution.

```shell
git clone --jobs 4 --recurse-submodules https://github.com/Zilliqa/scilla/
```

--------------------------------

### Clean APT Cache and Update Package Lists

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Removes existing APT package lists and source entries, then updates the package index to ensure fresh repository data and resolve potential conflicts.

```shell
sudo rm -rf /var/lib/apt/lists/*
sudo rm -rf /etc/apt/sources.list.d/*
sudo apt-get update
```

--------------------------------

### Execute Scilla Test Suite Manually with Parameters

Source: https://github.com/zilliqa/scilla/blob/master/CONTRIBUTING.md

This command allows manual execution of the Scilla test suite executable. It requires absolute paths for '-bin-dir' and '-tests-dir' and accepts additional space-separated parameters after '--' for custom configurations.

```Shell
dune exec tests/testsuite.exe -- <space-separated-parameters>
```

--------------------------------

### Scilla-server JSON-RPC API Specification

Source: https://github.com/zilliqa/scilla/wiki/Scilla-Server-API

Detailed specification of the Scilla-server's JSON-RPC interface, including available methods (`run`, `check`), their parameters (`argv`), and expected return values for both success and error scenarios. It outlines the server's single-threaded nature and how command-line arguments are mapped to JSON-RPC parameters.

```APIDOC
Scilla-server API:
  Type: JSON-RPC Server
  Concurrency: Single-threaded, processes one request at a time.

  Methods:
    run(argv: string[]): JSON
      Description: Executes a Scilla contract.
      Parameters:
        argv: string[] - A JSON array of strings, identical to command-line arguments for scilla-runner.
      Returns (on success):
        JSON - The 'result' field of the JSON-RPC response will contain a JSON object identical to the output emitted by scilla-runner. Implicitly assumes '-jsonerrors'.
      Returns (on failure):
        JSON - The 'error' field of the JSON-RPC response will be set.
          message: string | JSON - Can be a string (for incorrect argv) or a JSON object (identical to scilla-checker/runner error JSON).
          code: number - Standard JSON-RPC error code.

    check(argv: string[]): JSON
      Description: Checks a Scilla contract.
      Parameters:
        argv: string[] - A JSON array of strings, identical to command-line arguments for scilla-runner.
      Returns (on success):
        JSON - The 'result' field of the JSON-RPC response will contain a JSON object identical to the output emitted by scilla-checker. Implicitly assumes '-jsonerrors'.
      Returns (on failure):
        JSON - The 'error' field of the JSON-RPC response will be set.
          message: string | JSON - Can be a string (for incorrect argv) or a JSON object (identical to scilla-checker/runner error JSON).
          code: number - Standard JSON-RPC error code.

  Common Parameter:
    argv: string[]
      Description: A JSON array of strings representing the command-line arguments that would typically be passed to the scilla-runner or scilla-checker executable.
      Example: ["-init", "tests/runner/helloWorld/init.json", "-istate", "tests/runner/helloWorld/state_1.json", ...]

  Return Value (Success):
    JSON-RPC Response Object:
      jsonrpc: "2.0"
      result: JSON - Output of scilla-runner/checker.
      id: number | string - Request ID.

  Return Value (Failure):
    JSON-RPC Response Object:
      jsonrpc: "2.0"
      error:
        code: number - Error code.
        message: string | JSON - Error message. Can be a simple string (e.g., for argv parsing errors) or a JSON object (for scilla-runner/checker internal errors).
      id: number | string - Request ID.
```

--------------------------------

### Run Scilla Code Formatter

Source: https://github.com/zilliqa/scilla/wiki/Git-process-for-contributing-to-Scilla

Instructions on how to automatically format Scilla code to ensure it conforms to the project's coding standards. A Makefile target is provided for this purpose, and non-conformant code will be flagged by the Continuous Integration (CI) system.

```Shell
make fmt
```

--------------------------------

### List Available Scilla Tests

Source: https://github.com/zilliqa/scilla/blob/master/CONTRIBUTING.md

Use this command to display a comprehensive list of all individual tests available within the Scilla test suite. This helps in identifying specific tests for targeted execution or analysis.

```Shell
dune exec tests/testsuite.exe -- -list-test
```

--------------------------------

### C++ Scilla RPC Client Implementation

Source: https://github.com/zilliqa/scilla/wiki/Scilla-Server-API

The full C++ source code for `client.exe`. This program connects to the Scilla server via a Unix domain socket (`/tmp/scilla-server.sock`), parses command-line arguments to determine the RPC method and parameters, and then makes a JSON-RPC call. It handles the server's response, printing it to standard output, and includes basic error handling for RPC exceptions.

```cpp
#include <iostream>
#include <string.h>
#include <jsonrpccpp/client.h>
#include <jsonrpccpp/client/connectors/unixdomainsocketclient.h>

const char *SCILLA_SERVER_PATH = "/tmp/scilla-server.sock";
int main(int argc, char *argv[])
{
  if (argc < 2 || !strcmp(argv[1], "-h") ||
      !strcmp(argv[1], "-help") || !strcmp(argv[1], "--help"))
  {
    std::cerr << "Usage: " << argv[0] << " run|check ARGV...\n";
    return EXIT_FAILURE;
  }

  std::string method = argv[1];
  Json::Value params;
  Json::Value &server_argv = params["argv"];
  for (int i = 2; i < argc; i++) {
    server_argv.append(argv[i]);
  }

  jsonrpc::UnixDomainSocketClient c(SCILLA_SERVER_PATH);
  jsonrpc::Client client(c);

  try {
    Json::Value result = client.CallMethod(method, params);
    // The result is a string that contains a JSON.
    auto result_json_string = result.asString();
#if 1
    std::cout << result_json_string;
#else
    Json::Value scilla_output;
    // To do any kind of processing on the result, it must be parsed.
    if (!JSONUtils::GetInstance().convertStrtoJson(
          result_json_string, scilla_output))
    {
      std::cerr << "Error parsing Scilla output JSON\n";
      return EXIT_FAILURE;
    }
    std::cout << scilla_output.toStyledString();
#endif
    
  } catch (jsonrpc::JsonRpcException &e) {
    // if all the arguments were passed correctly to the server,
    // e.GetMessage() will be a (parseable) JSON string. Otherwise
    // it will be just an error message string describing the command
    // line usage. For this demo client, we just print whatever it is.
    std::cerr << e.GetMessage() << "\n";
    return EXIT_FAILURE;
  }

  return EXIT_SUCCESS;
}
```

--------------------------------

### Expected Output of Scilla Test Execution

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Shows the expected output from running the `eval-runner` test, indicating successful Scilla execution and the resulting variable bindings.

```text
{
  [a -> (Int32 42)],
  [y -> (Int32 42)],
  [f -> <closure>],
  [x -> (Int32 42)] }
```

--------------------------------

### Configure Emacs for Scilla Mode and Flycheck

Source: https://github.com/zilliqa/scilla/blob/master/README.md

Provides Emacs Lisp configuration snippets to enable Scilla major mode for `.scilla` and `.scillib` files, and to integrate Flycheck for real-time syntax checking and type reporting when `scilla-checker` is available.

```Emacs Lisp
;; For enabling flycheck mode for Scilla.
(setq scilla-root "/path/to/scilla/root")
;; Scilla mode
(load-file "/path/to/scilla-mode.el")
```

--------------------------------

### Run Scilla Test Suite

Source: https://github.com/zilliqa/scilla/blob/master/CONTRIBUTING.md

This command executes the full test suite for the Scilla project, leveraging the OUnit2 framework. It uses the Dune build system to invoke the 'testsuite' executable, displaying colored diffs for errors.

```Shell
make test
```

--------------------------------

### Create Global Opam Switch for Scilla

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

This command creates a new global opam switch named 'scilla' on your system. It is configured to use the `ocaml-base-compiler.4.12.0` version, providing a dedicated environment for Scilla development that is separate from other OCaml projects.

```shell
opam switch create scilla ocaml-base-compiler.4.12.0
```

--------------------------------

### Debug Scilla Checker/Runner

Source: https://github.com/zilliqa/scilla/blob/master/CONTRIBUTING.md

This command demonstrates how to debug Scilla bytecode executables like 'scilla_checker.bc' using 'ocamldebug'. It sets the 'LD_LIBRARY_PATH' environment variable and specifies necessary arguments for the debugger and the target binary.

```Shell
LD_LIBRARY_PATH=${PWD}/_build/default/src/base/cpp ocamldebug _build/default/src/runners/scilla_checker.bc -libdir src/stdlib -gaslimit 10000 tests/contracts/helloworld.scilla
```

--------------------------------

### Safely Clean Git Repository Excluding Local Opam Directory

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

When using a local opam switch, the `_opam` directory contains critical build artifacts and dependencies. This `git clean` command removes untracked files and directories (`-dfX`) but specifically excludes (`--exclude=\!_opam/**`) the `_opam` directory to prevent accidental deletion of the local opam environment.

```shell
git clean -dfX --exclude=\!_opam/**
```

--------------------------------

### Locate Scilla Executable Binaries

Source: https://github.com/zilliqa/scilla/blob/master/README.md

Specifies the default directory where compiled Scilla executable binaries are placed within the project structure.

```Shell
$PROJECT_DIR/bin
```

--------------------------------

### Evaluate Standalone Scilla Expression

Source: https://github.com/zilliqa/scilla/blob/master/README.md

Command to execute a standalone, closed Scilla expression using the `eval-runner` tool, specifying a gas limit and the path to the standard library.

```shell
eval-runner -gaslimit 10000 -libdir src/stdlib tests/eval/good/let.scilexp
```

--------------------------------

### Resolve OCaml `VERSION` File Case Sensitivity Errors on macOS

Source: https://github.com/zilliqa/scilla/wiki/macOS-troubleshooting

This snippet provides a shell command to resolve build failures on macOS related to incorrect case sensitivity of `VERSION` files in OCaml projects. These issues often manifest as `Wnonportable-include-path` warnings or `invalid preprocessing directive` errors during compilation. The command removes problematic `VERSION` files from opam switches, applicable for global switches.

```shell
find $(opam var --safe --strict root) -type f -name VERSION -exec rm {} \;
```

--------------------------------

### Run Specific Scilla Test

Source: https://github.com/zilliqa/scilla/blob/master/CONTRIBUTING.md

This command executes a single, specified test from the Scilla test suite by providing its unique identifier. The optional '-print-cli true' argument displays the exact command line used for the test execution.

```Shell
dune exec tests/testsuite.exe -- -only-test tests:4:checker:0:good:1:exptests:5:one-accept.scilla -print-cli true
```

--------------------------------

### Set PKG_CONFIG_PATH for Homebrew OpenSSL on macOS

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Configures the PKG_CONFIG_PATH environment variable to point to the Homebrew-installed OpenSSL package, which is necessary when using a non-default OpenSSL version on macOS.

```shell
export PKG_CONFIG_PATH="/usr/local/opt/openssl@_Version_/lib/pkgconfig:$PKG_CONFIG_PATH"
```

--------------------------------

### Scilla For-Loop (forall) Snippet

Source: https://github.com/zilliqa/scilla/wiki/VS-Code-Snippets

Create a "for-loop", i.e. a forall statement to call a procedure repeatedly on list elements.

```Scilla
forall ${1:list-to-iterate-on} ${2:procedure-name}
```

--------------------------------

### Scilla Checker Optional Flags

Source: https://github.com/zilliqa/scilla/blob/master/README.md

Documentation for an optional flag available with the `scilla-checker` tool, used to enable and display results from the cashflow checker.

```APIDOC
scilla-checker Options:
  -cf: Enable the cashflow checker and print its results.
```

--------------------------------

### Compare Scilla Contract ASTs using S-expressions

Source: https://github.com/zilliqa/scilla/wiki/Scilla-AST-comparison

This shell script sequence demonstrates how to generate the S-expression representation of two Scilla contracts using the `scilla-fmt` tool and then compare these representations using the `diff` utility. The comparison is performed on the de-annotated S-expression format, which is useful for identifying structural differences between contracts.

```shell
scilla-fmt -h --sexp --deannot contract1.scilla > contract1.sexp
scilla-fmt -h --sexp --deannot contract2.scilla > contract2.sexp
diff contract1.sexp contract2.sexp
```

--------------------------------

### Run Group of Scilla Tests

Source: https://github.com/zilliqa/scilla/blob/master/CONTRIBUTING.md

This command allows running a predefined group of tests, such as all typechecking tests identified by 'checker'. It's useful for focused testing of specific functionalities or modules within the project.

```Shell
dune exec -- tests/testsuite.exe -only-test tests:4:checker
```

--------------------------------

### Type-check Scilla Contract with scilla-checker

Source: https://github.com/zilliqa/scilla/blob/master/README.md

Command to perform type-checking on a Scilla contract using the `scilla-checker` tool, including options for gas limit and standard library path. The output indicates success with JSON or provides a type error trace.

```shell
scilla-checker -gaslimit 10000 -libdir src/stdlib tests/contracts/auction.scilla
```

--------------------------------

### Lint Scilla Codebase

Source: https://github.com/zilliqa/scilla/blob/master/CONTRIBUTING.md

This command performs linting checks on the Scilla codebase to identify potential issues before submitting a pull request. It utilizes 'ocamlformat', 'opam', and 'shellcheck' for comprehensive analysis of code quality.

```Shell
make lint
```

--------------------------------

### Pseudo-code for Dynamic Scilla Value Input

Source: https://github.com/zilliqa/scilla/wiki/UI-design-for-inputting-ADT-values

This pseudo-code defines the `get_input` function, which recursively prompts the user for a Scilla value based on its `ConcreteType`. It handles primitive types by direct text input and Algebraic Data Types (ADTs) by presenting constructor choices and recursively gathering arguments, ultimately building a structured JSON object.

```Pseudo-code
  Json get_input(ConcreteType t) {
    if (t is primitive type) {
       text = get_input_plain_text();
       return Json (text);
    } else {
       // Concrete ADT
       string constructors_names[];
       foreach (c in t.tmap) {
          constructor_names.append(t.tmap.cname);
       }
       constructor = get_input_from_menu(constructor_names);
       Json value;
       value["constructor"] = constructor;
       value["argtypes"] = t.tmap[constructor].argtypes;
       foreach (t' in t.tmap[constructor].argtypes) {
         value["arguments"].append(get_input(t'));
       }
    }
  }
```

--------------------------------

### Update Scilla Checker Gold Files

Source: https://github.com/zilliqa/scilla/blob/master/CONTRIBUTING.md

This command is used to update the 'gold'-files, which store the expected output for 'checker' tests. Running this command promotes new test outputs to become the new reference for future test runs.

```Shell
dune exec -- tests/testsuite.exe -only-test tests:4:checker -update-gold true
```

--------------------------------

### Define a Simple Scilla Algebraic Data Type (ADT)

Source: https://github.com/zilliqa/scilla/wiki/UI-design-for-inputting-ADT-values

This OCaml code defines a simple Algebraic Data Type (ADT) named `MyAdt` with three distinct constructors. `MyConstructor1` takes an `Int32` and a `String`, `MyConstructor2` takes a `ByStr20`, and `MyConstructor3` is a nullary constructor, meaning it takes no arguments.

```OCaml
type MyAdt =
  | MyConstructor1 of Int32 String
  | MyConstructor2 of ByStr20
  | MyConstructor3
```

--------------------------------

### JSON Configuration for Scilla Merger Name Collision Resolution

Source: https://github.com/zilliqa/scilla/blob/master/src/merge/README.md

This JSON configuration file is used by the `scilla-merger` tool to resolve name collisions when merging multiple Scilla contracts. It specifies a list of replacements, where each entry identifies a specific file, line number, the original conflicting identifier (`replacee`), and its desired new name (`replacement`). This helps in avoiding conflicts when functions or variables with the same name exist across different contracts being merged.

```json
{
  "replacements": [
    {
      "filename": "tests/merge/static/remote_collisions11.scilla",
      "line": 19,
      "replacee": "m_f",
      "replacement": "remoteCollisions12_m_f"
    },
    {
      "filename": "tests/merge/static/remote_collisions11.scilla",
      "line": 17,
      "replacee": "a_f",
      "replacement": "remoteCollisions13_a_f"
    }
  ]
}
```

--------------------------------

### Scilla Read Blockchain State Snippet

Source: https://github.com/zilliqa/scilla/wiki/VS-Code-Snippets

Read from blockchain state.

```Scilla
${1:identifier} <-& ${2:blockchain-query};
```

--------------------------------

### Increase File Descriptor Limit for Scilla Tests on macOS

Source: https://github.com/zilliqa/scilla/blob/master/INSTALL.md

Increases the maximum number of open file descriptors to 1024, which may be required for running Scilla tests using Dune on macOS to prevent 'Too many open files' errors.

```shell
ulimit -n 1024
```

--------------------------------

### Define a Polymorphic Scilla Algebraic Data Type (ADT)

Source: https://github.com/zilliqa/scilla/wiki/UI-design-for-inputting-ADT-values

This OCaml code illustrates the definition of a polymorphic Algebraic Data Type (ADT) named `MyPAdt`. It introduces a type parameter `'A`, allowing the ADT to be generalized and instantiated with different concrete types later, such as `Int32` or `String`.

```OCaml
type 'A MyPAdt =
  | MyPConstructor1 of 'A String
  | MyPConstructor2 of ByStr20
  | MyPConstructor3
```
Tokens:
Raw