414 lines
13 KiB
ReStructuredText
414 lines
13 KiB
ReStructuredText
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 the various ``tezos-*.opam`` files.
|
||
|
||
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:
|
||
|
||
- ``./src/bin_node/tezos-sandboxed-node.sh``
|
||
- ``./src/bin_client/tezos-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``.
|
||
|
||
::
|
||
|
||
./src/bin_node/tezos-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``:
|
||
|
||
::
|
||
|
||
./src/bin_node/tezos-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:
|
||
|
||
::
|
||
|
||
./src/bin_node/tezos-sandboxed-node.sh 1 --connections 0
|
||
|
||
Once your node(s) is/are running, open a new terminal and initialize the
|
||
“sandboxed” client data:
|
||
|
||
::
|
||
|
||
eval `./src/bin_client/tezos-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)"
|
||
},
|
||
|
||
/* Configuration for the validator and mempool parameters */
|
||
|
||
"shell": {
|
||
|
||
/* The number of peers to synchronize with
|
||
before declaring the node 'bootstrapped'. */
|
||
|
||
"bootstrap_threshold": 4
|
||
|
||
}
|
||
}
|
||
|
||
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
|
||
----------------------
|
||
|
||
Tezos is distributed with two command line tools: a minimal command
|
||
line wallet ``tezos-client``, and an administration tool
|
||
``tezos-admin-client``.
|
||
|
||
Their command line interfaces are described
|
||
:ref:`here<tezos_client_commands>` and
|
||
:ref:`here<tezos_admin_client_commands>`.
|