Introduction

Before we move on to the first chapter, here are two things you should know:

• Installation options;
• How a notebook is structured.

Try online

In order to feel what interactive notebooks are you can open course chapters in the Binder service, that provides a temporary Jupyter environment.

NOTE

Your changes won't be saved unless you download the notebook to your computer.
For regular use consider local setup (options below).

Run in Docker

Ensure you have Docker installed.

docker pull bakingbad/michelson-kernel
docker run --rm -it -p 127.0.0.1:8888:8888 -v $(pwd):/home/jupyter/notebooks bakingbad/michelson-kernel

Open http://127.0.0.1:8888 in your browser.

Note, that the notebooks folder is mounted to your local filesystem by default, so you won't loose any changes made.

Install Jupyter

First of all, install several crypto libraries:

• Ubuntu: sudo apt install libsodium-dev libsecp256k1-dev libgmp-dev
• MacOS: brew install libsodium libsecp256k1 gmp
• Windows: follow the guide

Ensure you have a suitable Python version (3.5+). The recomended way is pyenv. Make sure you have installed all the dependencies first.

pip install jupyter pytezos
michelson-kernel install
jupyter notebook

Open the link from the command output, create new notebook with Michelson kernel.

Notebook workflow

A notebook is a set of cells that can contain text (markdown), executable code, and the result of an execution.

The code is executed using a special extension called the kernel. Michelson kernel is actually a wrapped interpreter that supports an extended instruction set: in addition to the language primitives it also expands Michelson macros and special debugging helpers.

Code block

This is a cell holding a Michelson expression that can be executed. Keep in mind, that all cells share the state, so the order of execution does matter.

PUSH string "Hello" ;

Execution log

By default verbose logging is enabled and you will see a step-by-step instruction execution.

stdout
PUSH: push Hello;

Errors

In case of a runtime error you will see a red box with the message and traceback.

stderr
MichelsonRuntimeError

Stack values

If a stack entry occurs as a result of the execution, you will see the value, its type, and name (if any).

value	type
"Hello"	string

Helpers and macros

You will notice that different primitives are painted in different colors. The kernel distinguishes between standard language instructions, macros (not part of the specification), and helpers that do not work outside the Jupyter environment.

DROP ;  ## Michelson instruction
FAIL ;  ## Michelson macro
DUMP ;  ## Jupyter kernel helper