ligo/README.md

TEZOS
=====

Tezos is a distributed consensus platform with meta-consensus capability. Tezos
not only comes to consensus about state, like BTC or ETH. It also comes to
consensus about how the protocol and the nodes should adapt and upgrade.

See https://www.tezos.com/ for more information about the project.


Build instructions
------------------

To compile Tezos, you need an OCaml compiler (version 4.04.2) and all the
libraries listed in `src/tezos-deps.opam`.

The best way to install all dependencies is by first installing
[OPAM](https://opam.ocaml.org/), the OCaml package manager.

Then, you need to create a new switch alias for Tezos. A switch is
your own version of the OPAM configuration, including the OCaml
compiler, all packages, and package manager configuration related to
your project. This is necessary so that the project doesn't conflict
with other OCaml projects or other versions of Tezos.

```
opam update
opam switch "tezos" --alias-of 4.04.2
```

Note that if you previously created a switch named `tezos` but with an
older OCaml version you need to remove the switch with `opam switch
remove "tezos"`.

When the switch is ready, you need to activate it:

```
eval `opam config env`
```

Install the libraries which Tezos depends on:

```
make build-deps
```

While building the dependencies, `opam` is able to handle correctly
the OCaml libraries but it is not always able to handle all external C
libraries we depend on. On most system, it is able to suggest a call
to the system package manager but it currently does not handle version
check. In particular, the `libsodium-dev` packages on Ubuntu is too
old for building Tezos, we rely on version `1.0.11` at least.

At last, compile the project:

```
make
```

This should produce three binaries:

* `tezos-node`: the tezos daemon itself;
* `tezos-client`: a minimal command-line client;
* `tezos-protocol-compiler`: a protocol compiler used for developing new version of the economic protocol.

Currently Tezos is being developed for Linux only. It should work on mac OS,
but it has not been tested recently. A Windows port is in progress.


Note that, when executing `make build-deps`, OPAM will detect if
required system dependencies are installed. However, it is not able to
detect which versions you actually have. Typically, `make` will
probably fail if you have an libsodium < 1.0.11. In this case, make
sure you have a recent version of libsodium and libsodium-dev, or
download and install them from, eg,
https://pkgs.org/download/libsodium18 and
https://pkgs.org/download/libsodium-dev

Running the node
----------------

So far there is no official Tezos network being run, but you might run a local
test network (the development team is running its own testnet, if you're interested
in joining this network, please make a request on our slack channel. We have
limited support abilities at the moment but we'll try to help you best we can).

Use the following command to run a node that will accept incoming
connections:

```
./tezos-node identity generate 24.
```

This will first generate a new node identity and compute the
associated stamp of proof-of-work. Then, the node will listen to
connections coming in on `[::]:9732`. All used data is stored at
`$HOME/.tezos-node/`. For example, the default configuration file is
at `$HOME/.tezos-node/config.json`.

To run multiple nodes on the same machine, you can duplicate and edit
`$HOME/.tezos-node/config.json` while making sure they don't share paths to the
database or any other data file (cf. options `db.store` ; `db.context` ;
`db.protocol`, `net.peers-metadata` and `net.identity`).

You could also let Tezos generate a config file by specifying options on the
command line. For instance, if `$dir/config.json` does not exist, the following
command will generate it and replace the default values with the values from
the command line:

```
./tezos-node run --data-dir "$dir" --net-addr localhost:9733
```

The Tezos server has a built-in mechanism to discover peers on the local
network (using UDP packets broadcasted on port 7732).

If this mechanism is not sufficient, one can provide Tezos with a list of
initial peers, either by editing the option `net.bootstrap-peers` in the
`config.json` file, or by specifying a command line parameter:

```
./tezos-node run \
             --data-dir "$dir" --net-addr localhost:2023 \
             --peer localhost:2021 --peer localhost:2022
```

If `"$dir"/config.json` exists, the command line options override those
read in the config file. By default, Tezos won't modify the content of an
existing `"$dir"/config.json` file. But, you may explicit ask the node
to reset or to update the file according to the command line parameters
with the following commands line:

```
./tezos-node config reset --data-dir "$dir" --net-addr localhost:9733
./tezos-node config update --data-dir "$dir" --net-addr localhost:9734
```

Running the node in a sandbox
-----------------------------

To run a 'localhost-only' instance of a Tezos network, we provide two
helper scripts:

- `./scripts/launch-sandboxed-node.sh`
- `./scripts/init-sandboxed-client.sh`

For instance, if you want to run local network with two nodes, in a
first terminal, the following command will initialize a node listening
for peers on port `19731` and listening for RPC on port `18731`.

```
./scripts/launch-sandboxed-node.sh 1
```

This node will store its data in a temporary directory which will be
removed when the node is killed.

To launch the second node, just run the following command, it will
listen on port `19739` and `18739`:

```
./scripts/launch-sandboxed-node.sh 9
```

You might replace `1` or `9` by any number in between if you want to
run more than two nodes. But, if you intend to run a single node
network, you might remove the spurious "Too few connections" warnings
by lowering the number of expected connection, by running the
following command instead:

```
./scripts/launch-sandboxed-node.sh 1 --connections 0
```

Once your node(s) is/are running, open a new terminal and initialize
the "sandboxed" client data:

```
eval `./scripts/init-sandboxed-client.sh 1`
```

It will initialize the client data in a temporary directory. It will
also defines in the current shell session an alias `tezos-client`
preconfigured for communicating the same-numbered node. For instance:

```
$ tezos-client rpc call blocks/head/hash
{ "hash": "BLockGenesisGenesisGenesisGenesisGenesisGeneskvg68z" }
```

When you bootstrap a new network, the network is initialized with a
dummy economic protocol, called "genesis". If you want to run the same
protocol than the alphanet, `init-sandboxed-client` also defines an
alias `tezos-activate-alpha`, that you need to execute once for
activating the whole network. For instance:

```
$ tezos-client rpc call blocks/head/protocol
{ "protocol": "ProtoGenesisGenesisGenesisGenesisGenesisGenesk612im" }
$ tezos-activate-alpha
Injected BMBcK869jaHQDc
$ tezos-client rpc call blocks/head/protocol
{ "protocol": "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK" }
```

Configuration options
---------------------

Here is an example configuration file with all parameters
specified. Most of the time it uses default values, except for cases
where the default is not explanatory enough (i.e. "bootstrap-peers" is
an empty list by default). Comments are not allowed in JSON, so this
configuration file would not parse. They are just provided here to
help writing your own configuration file if needed.


```
{

  /* Location of the data dir on disk. */

  "data-dir": "/home/tezos/my_data_dir"

  /* Configuration of net parameters */

  "net": {

    /* Floating point number between 0 and 256 that represents a
    difficulty, 24 signifies for example that at least 24 leading
    zeroes are expected in the hash. */

    "expected-proof-of-work": 24.5,

    /* List of hosts. Tezos can connect to both IPv6 and IPv4
    hosts. If the port is not specified, default port 9732 will be
    assumed. */

    "bootstrap-peers": ["::1:10732", "::ffff:192.168.1.3:9733", "mynode.tezos.com"],

    /* Specify if the network is closed or not. A closed network
    allows only peers listed in "bootstrap-peers". */

    "closed": false,

    /* Network limits */

    "limits": {

      /* Delay granted to a peer to perform authentication, in
      seconds. */

      "authentication-timeout": 5,

      /* Strict minimum number of connections (triggers an urgent
      maintenance). */

      "min-connections": 50,

      /* Targeted number of connections to reach when bootstraping /
      maintaining. */

      "expected-connections": 100,

      /* Maximum number of connections (exceeding peers are
      disconnected). */

      "max-connections": 200,

      /* Number above which pending incoming connections are
      immediately rejected. */

      "backlog": 20,

      /* Maximum allowed number of incoming connections that are
      pending authentication. */

      "max-incoming-connections": 20,

      /* Max download and upload speeds in KiB/s. */

      "max-download-speed": 1024,
      "max-upload-speed": 1024,

      /* Size of the buffer passed to read(2). */

      "read-buffer-size": 16384,
    }
  },

  /* Configuration of rpc parameters */

  "rpc": {

    /* Host to listen to. If the port is not specified, the default
    port 8732 will be assumed. */

    "listen-addr": "localhost:8733",

    /* Cross Origin Resource Sharing parameters, see
    https://en.wikipedia.org/wiki/Cross-origin_resource_sharing. */

    "cors-origin": [],
    "cors-headers": [],

    /* Certificate and key files (necessary when TLS is used). */

    "crt": "tezos-node.crt",
    "key": "tezos-node.key"
  },

  /* Configuration of log parameters */

  "log": {

    /* Output for the logging function. Either "stdout", "stderr" or
    the name of a log file . */

    "output": "tezos-node.log",

    /* Verbosity level: one of 'fatal', 'error', 'warn', 'notice',
    'info', 'debug'. */

    "level": "info",

    /* Fine-grained logging instructions. Same format as described in
    `tezos-node run --help`, DEBUG section. In the example below,
    sections "net" and all sections starting by "client" will have
    their messages logged up to the debug level, whereas the rest of
    log sections will be logged up to the notice level. */

    "rules": "client* -> debug, net -> debug, * -> notice",

    /* Format for the log file, see
    http://ocsigen.org/lwt/dev/api/Lwt_log_core#2_Logtemplates. */

    "template": "$(date) - $(section): $(message)"
  }
}
```

Debugging
---------

It is possible to set independant log levels for different logging
sections in Tezos, as well as specifying an output file for
logging. See the description of log parameters above as well as
documentation under the DEBUG section diplayed by `tezos-node run
--help'.


JSON/RPC interface
------------------

The Tezos node provides a JSON/RPC interface. Note that it is an RPC, and it is
JSON based, but it does not follow the "JSON-RPC" protocol. It is not active by
default and it must be explicitely activated with the `--rpc-addr` option.
Typically, if you are not trying to run a local network and just want to
explore the RPC, you would run:

```
./tezos-node run --rpc-addr localhost
```

The RPC interface is self-documented and the `tezos-client` executable is able
to pretty-print the RPC API. For instance, to see the API provided by the Tezos
Shell:

```
./tezos-client rpc list
```

To get API attached to the "genesis" block, including the remote procedures
provided by the associated economic protocol version:

```
./tezos-client rpc list /blocks/genesis/
```

You might also want the JSON schema describing the expected input and output of
a RPC. For instance:

```
./tezos-client rpc schema /blocks/genesis/hash
```

Note: you can get the same information, but as a raw JSON object, with a simple
HTTP request:

```
wget --post-data '{ "recursive": true }' -O - http://localhost:8732/describe
wget --post-data '{ "recursive": true }' -O - http://localhost:8732/describe/blocks/genesis
wget -O - http://localhost:8732/describe/blocks/genesis/hash
```



The minimal CLI client
----------------------

Work in progress.

See `./tezos-client -help` for available commands.