Commit f626e9d6 authored by Marco Stronati's avatar Marco Stronati

Doc: new introduction howto{get,use,run}

parent 8fb52eab
......@@ -7,31 +7,33 @@
Welcome to the Tezos Developer Documentation!
=============================================
The Project
-----------
Tezos is a distributed consensus platform with meta-consensus
capability. Tezos not only comes to consensus about the state of its ledger,
like Bitcoin or Ethereum. It also attempts to come to consensus about how the
protocol and the nodes should adapt and upgrade.
- Developer documentation is available online at http://tezos.gitlab.io/master
always in sync with the master branch (which may be desynchronized with
the code running on the live networks, replace ``master`` in the URL by the
branch of your choice: betanet, alphanet, zeronet, to make sure you are
consulting the right API version)
- The official Tezos website https://tezos.com/ contains more information about the
project.
- All development now happens on GitLab at https://gitlab.com/tezos/tezos
The Tezos Alpha (test) network has been live and open since February 2017.
- Developer documentation is available online at https://tezos.gitlab.io/master
The documentation is automatically generated for the master branch and the
three official network branches `betanet <https://tezos.gitlab.io/betanet>`_,
`alphanet <https://tezos.gitlab.io/alphanet>`_,
`zeronet <https://tezos.gitlab.io/zeronet>`_. Make sure you are
consulting the right API version.
- The website https://tezos.com/ contains more information about the project.
- All development happens on GitLab at https://gitlab.com/tezos/tezos
The Tezos Beta (experimental) network has been live and open since June 2018.
The source code of Tezos is placed under the MIT Open Source License.
The Community
-------------
- More information on joining the Alphanet at :ref:`here <alphanet>`.
- Several community built block explorers are available:
- http://ostez.com
- http://tzscan.io
- https://tezos.id
- https://tezex.info
- A few community run websites collect useful Tezos links:
......@@ -39,24 +41,76 @@ The Tezos Beta (experimental) network has been live and open since June 2018.
- https://tezos.rocks
- There is a matrix channel *Tezos* that you can join `here <https://riot.im/app/#/room/#tezos:matrix.org>`_.
- There is a *#tezos* channel on *freenode* that is reserved for technical discussions
- There is a sub-reddit at https://www.reddit.com/r/tezos/
- There is also a community FAQ at https://github.com/tezoscommunity/faq/wiki/Tezos-Technical-FAQ
- There is a *#tezos* IRC channel on *freenode* that is reserved for technical discussions
The source code of Tezos is placed under the MIT Open Source License.
.. toctree::
:maxdepth: 2
:caption: Introduction:
The Networks
------------
.. _alphanet:
Alphanet
~~~~~~~~
Tezos Alphanet is a test network for the Tezos blockchain with a
faucet to obtain free tezzies (see :ref:`faucet`).
It is updated and rebooted rarely and it is either running the same
code as beta or the next version that will become beta in a few weeks.
It is the reference network for developers wanting to test their
software before going to beta and for users who want to familiarize
themselves with Tezos before using their real tezzies.
We offer support for Alphanet on IRC.
The Tezos Alpha (test) network has been live and open since February 2017.
.. _zeronet:
Zeronet
~~~~~~~
Zeronet is the most cutting-edge development network of Tezos. It is
restarted without notice, possibly several times a day.
This network is mostly used internally by the Tezos developers and may
have *different constants* that Alphanet or Betanet.
We offer no support for the Zeronet.
.. _betanet:
Betanet
~~~~~~~
The Tezos Beta (experimental) network is the current incarnation of
the Tezos blockchain.
There is no faucet but real tezzies that have been allocated to the
donors of July 2017 ICO (see :ref:`activate_fundraiser_account`).
It is the step before the full Tezos mainnet, with a `few caveats
<https://tezosfoundation.ch/news/tezos-betanet-expectations>`_.
The Tezos Beta (experimental) network has been live and open since
`June 30th 2018 <https://tezosfoundation.ch/news/tezos-betanet-launch>`_.
Getting started
---------------
The best place to start exploring the project is following the How Tos
in the :ref:`introduction <howtoget>`.
introduction/howto
introduction/contributing
.. toctree::
:maxdepth: 2
:caption: Test Networks:
:caption: Introduction:
introduction/alphanet
introduction/zeronet
introduction/howtoget
introduction/howtouse
introduction/howtorun
introduction/various
introduction/contributing
.. toctree::
:maxdepth: 2
......@@ -72,6 +126,7 @@ The source code of Tezos is placed under the MIT Open Source License.
:maxdepth: 2
:caption: Developer Tutorials:
tutorials/rpc
tutorials/data_encoding
tutorials/error_monad
tutorials/michelson_anti_patterns
......
This diff is collapsed.
Changelog
---------
Reset 2018-05-03
~~~~~~~~~~~~~~~~
[Alpha]
- New faucet : https://faucet.tzalpha.net
- `secp256k1` as an alternative to `ed25519`
- 32 endorsers per blocks (was 15)
- Delegation rights are now frozen 5 cycles in advance (approx 15 days
in mainnet or 10 hours on zeronet);
- Security deposits are recovered after 5 cycles;
- Rewards and fees are earned after 5 cycles;
- Pending deposits and fees count in the staking balance of a delegate;
- Delegates will be tagged as "deactivated" after 5 cycles of
inactivity and they will lose their baking rights;
- Do not allow revealing the same endorsement twice.
- Tez values now have 6 decimals instead of two. The syntax used by
the client and Michelson use comma separators every three
digits, before and after the dot. For instance, 3 million tez and 10
µtez is written `3,000,000.000,01`. The syntax in JSON is the raw
amount in µtez, either as a number without decimals or as a decimal
string, for the same example we would get `"3000000000010"`.
[Node]
- Rewrite of the RPC library to handle content types, to enable binary
RPCs and proper HTTP verbs. The next version will probably break the
HTTP API.
- Now that we don't use the git backend anymore, we finally updated
the context hashing function from SHA1 to Blake2B.
[Michelson]
- Set a maximum type size, as a simple solution to avoid some type
checker abuses where types can grow exponentially.
- Annotations are now correctly handled by macros.
[Build]
- Split the code base into separate OPAM packages.
Patch 2018-01-15
~~~~~~~~~~~~~~~~
[Node]
- Fix a performance issue in block locator computation
Reset 2017-11-20
~~~~~~~~~~~~~~~~
[Alphanet]
- Limit the number of faucet operations at 5 per block.
[Client]
- Autocomplete scripts for bash.
- Smart contracts are now non spendable by default.
- Add a debug command to list invalid blocks.
[Node]
- Prevent potential stack overflow in validation.
- Fix concurrency issue where operations were cleared from
memory before being used.
- Continue background work on the multipass validator:
cleanup and document data structures, better logging
of resource requests, enhance requests for the same piece
of data to multiple peers, split the code in smaller
simpler components.
- P2p: fix issue with data greater than 2^16 bytes
- Irmin: use an experimental LMDB backend
[Build]
- Refactor the economic protocol amendment code. Protocols are
now compiled to functors, taking the type signature of their
runtime environment as parameter. This simplifies the
dependencies, and will allow third party developers to
instantiate economic protocols in other contexts than the node.
- Switch from Makefiles to jbuilder, yay!
- Rename (hopefully) all occurrences of "mining" into "baking".
[Michelson]
- Introduce Micheline, the (now independent) IR of Michelson.
The parser and printer should now be used on their own, outside
of the client or node.
- Implement a basic semantics of annotations.
The typechecker now propagates annotations on types throughout the
code, and tagging instructions with an annotation allows the
programmer to reannotate the element produced by the instruction.
The emacs mode displays propagated annotations.
- Add a version of `ITER` that takes a static code block and expects
a collection on the initial stack, and works like a `LOOP`, pushing
the element of the collection one at a time on the stack. This is
like `REDUCE` but using a static code block instead of a dynamic
lambda. In the same vein, `MAP` can take a code block.
- Add `LOOP_LEFT` that uses a different type for the accumulator and
the return value. Continues while the top of the stack is `Left 'a`
and stops on `Right 'b`.
- Change timestamps to be arbitrary precision relative integers.
- Add `SIZE` on lists.
Reset 2017-11-17
~~~~~~~~~~~~~~~~
[Node]
- P2p: fix issue with data greater then 2^16 bytes
- Irmin: restore usage `git-repack`... (mistakenly removed)
Reset 2017-10-13
~~~~~~~~~~~~~~~~
[Client]
- Fix missing nonce revelation at end of cycle.
- New command line analyzer and better help pages.
[Node]
- Various small fixes and error message enhancements.
[Alphanet]
- Use older leveldb-1.18 as upgrade to the newer version made the
node crash.
[Michelson]
- Split the `key` type into `key` and `key_hash` to
prevent an error raised when using an unrevealed key.
Reset 2017-09-21
~~~~~~~~~~~~~~~~
[Node]
- fix a performance issue in roll storage
[Doc]
- improve scripts and documentations on how to run sandboxed node
or a local private network
[Client]
- add an option `-log-requests`. All RPC requests and responses to the
node are logged on `stderr`.
[Michelson]
- Split the `key` type into `key` and `key_hash` to
prevent an error raised when using an unrevealed key.
Reset 2017-08-10
~~~~~~~~~~~~~~~~
This update includes changes in the on-disk state of the node and in
the format of blocks and operations. It thus requires a chain reset.
Main changes includes:
[Doc]
- The documentation previously available on the Slack channel is now
available at:
https://raw.githubusercontent.com/tezos/tezos/alphanet/README.md
- The `alphanet` branch of the github repository is now automatically
synchronized with `alphanet` docker image. And the latest version of
the `alphanet.sh` is available at:
https://raw.githubusercontent.com/tezos/tezos/alphanet/scripts/alphanet.sh
No need to update manually though, the script auto-update itself
when running:
./alphanet.sh restart
Or:
./alphanet.sh update_script
[Michelson]
- minor language enhancements, mostly resulting from the feedback of
Milo's daily challenge:
https://www.michelson-lang.com/
- the alphanet scripts now understands a container: prefix wherever a
file: prefix is accepted, temporarily copying the file into the
container, and the emacs-mode is aware of that
[Node]
- Operations now include a block hash in their header. Such an
operation could only be included in a successor of this block.
- The economics protocol now refuses blocks that includes an operation
forged more than 64 blocks in the past. As any constants set by the
economic protocol, it is amendable by a vote.
- Header of blocks now includes a hash of the "context" that result
from its validation. This is currently the SHA1 of the git commit,
but this will be changed in a near future for a safer cryptographic
hash.
- The node does not need anymore to maintain a full index of the
operation to operate. This greatly reduce the memory and disk usage.
- The node now builds against `irmin.1.3` where some of our code and
optimizations were upstreamed. We were previously stuck to
irmin.0.12.
[CI]
- This is not directly visible in the alphanet, but our CI
infrastructure is now ready for open development.
More about that soon (or later).
......@@ -7,6 +7,21 @@ Introduction
The purpose of this document is to help contributors get started with
the Tezos OCaml codebase.
Reporting issues
----------------
The simplest way to contribute to Tezos is to report issues that you may
find with the software on `gitlab <https://gitlab.com/tezos/tezos/issues>`__.
If you are unsure about an issue ask on IRC first and always make sure
to search the existing issues before reporting a new one.
Some info that are probably important to include in the description:
the architecture (e.g. *ARM64*), the operating system (e.g. *Debian
Stretch*), the network you are connected to (e.g. *Alphanet*), the
binary or component (e.g. *tezos-node crashes* or *rpc X returns Y
while Z was expected*).
First steps
-----------
......
.. _howtoget:
How to get Tezos
================
In this How To we explain how to get up-to-date binaries to run Tezos
for each network.
You can either use the docker images, which is easier, or build from
sources.
Docker images
-------------
The recommended way for running an up-to-date Tezos node is to use the
docker images that are automatically generated from the GitLab
repository and published on `DockerHub
<https://hub.docker.com/r/tezos/tezos/>`_.
The script ``alphanet.sh`` is provided to help download the right
image for each network and run a simple node.
Its only requirement is a working installation of `Docker
<https://www.docker.com/>`__ and docker compose on a machine with
architecture **x86_64**.
Although we only officially support Linux, the script has been tested
with success in the past on windows/mac/linux.
The same script can be used to run Alphanet or Zeronet, it suffices to
rename it, it downloads a different image based on its name.
For example, to run Alphanet:
::
wget https://gitlab.com/tezos/tezos/raw/master/scripts/alphanet.sh
chmod +x alphanet.sh
Alternatively, to run Zeronet:
::
wget -O zeronet.sh https://gitlab.com/tezos/tezos/raw/master/scripts/alphanet.sh
chmod +x zeronet.sh
In the following we assume you are running Alphanet.
You are now one step away from a working node:
::
./alphanet.sh start
This will download the right docker image for your chosen network,
launch 3 docker containers running the node, the baker and the
endorser.
The first launch might take a few minutes to download the
docker images and synchronize the chain.
Every call to ``alphanet.sh`` will check for updates of the node and
will fail if your node is not up-to-date. For updating the node, simply
run:
::
./alphanet.sh restart
If you prefer to temporarily disable automatic updates, you just have to
set an environment variable:
::
export TEZOS_ALPHANET_DO_NOT_PULL=yes
See ``./alphanet.sh --help`` for more informations about the
script. In particular see ``./alphanet.sh client --help`` or the
:ref:`online manual<client_manual>` for more information about
the client. Every command to the ``tezos-client`` can be
equivalently executed using ``./alphanet.sh client``.
Build from sources
------------------
**TL;DR**: Typically you want to do:
::
sudo apt install -y git m4 build-essential patch unzip bubblewrap wget
wget https://github.com/ocaml/opam/releases/download/2.0.0/opam-2.0.0-x86_64-linux
sudo cp opam-2.0.0-x86_64-linux /usr/local/bin/opam
sudo chmod a+x /usr/local/bin/opam
git clone https://gitlab.com/tezos/tezos.git
cd tezos
git checkout alphanet
opam init --bare
make build-deps
eval $(opam env)
make
export PATH=~/tezos:$PATH
source ./src/bin_client/bash-completion.sh
export TEZOS_CLIENT_UNSAFE_DISABLE_DISCLAIMER=Y
Environment
~~~~~~~~~~~
Currently Tezos is being developed for Linux x86_64, mostly for
Debian/Ubuntu and Archlinux.
The following OSes are reported to work:
- macOS/x86_64
- Linux/armv7h (32 bits) (Raspberry Pi3, etc.)
- Linux/aarch64 (64 bits) (Raspberry Pi3, etc.)
A Windows port is feasible and might be developed in the future.
Get the sources
~~~~~~~~~~~~~~~
Tezos *git* repository is hosted at `GitLab
<https://gitlab.com/tezos/tezos/>`_. All development happens here. Do
**not** use our `GitHub mirror <https://github.com/tezos/tezos>`_
which we don't use anymore and only mirrors what happens on GitLab.
You also need to **choose the branch** of the network you want to connect
to: *alphanet*, *zeronet* or *betanet*.
The *master* branch is where code is merged, but there is no test
network using the master branch directly.
Install OPAM
~~~~~~~~~~~~
To compile Tezos, you need the `OPAM <https://opam.ocaml.org/>`__
package manager, version *2.0.0*. This is the current latest
version of OPAM and our build script will always use the latest
released version (or prerelease) of OPAM. The build script will take
care of setting-up OPAM, download the right version of the OCaml
compiler, and so on.
Use ``opam init --bare`` to avoid compiling the OCaml compiler now: it
will be done in the next step.
Install Tezos dependencies with OPAM
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Install the OCaml compiler and the libraries which Tezos depends on:
::
make build-deps
This command creates a local opam switch ``_opam`` where the right
version of OCaml is compiled and installed (this takes a while but
it's only done once).
After OCaml it will start with Tezos 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.
Once the dependencies are done we can update opam's environment to
refer to the new switch and compile the project:
::
eval $(opam env)
make
Lastly you can also add Tezos binaries to your ``PATH`` variable,
activate bash autocompletion and after reading the Disclaimer a few
hundred times you are allowed to disable it with
``TEZOS_CLIENT_UNSAFE_DISABLE_DISCLAIMER=Y``.
To add the default opam repository at a lower priority (for example to
install or test other opam packages), you can use the following command:
::
opam repo add default --rank=-1
.. _howtorun:
How to run Tezos
================
In this section we discuss how to take part in the protocol that runs
the network.
There are two main ways to participate in the consensus, delegating
your coins and running a delegate.
To learn more about the protocol refer to :ref:`this section <proof-of-stake>`.
Delegating your coins
---------------------
If you don't want to deal with the complexity of running your own
delegate, you can always take part in the protocol by delegating your
coins to one.
Implicit accounts cannot have a delegate, so the first step is to
originate an account, transfer your tezzies there and set a delegate.
Notice that an originated account is a special case of a contract
without code, so it is still necessary to pay for its small storage
(see `originated_account`).
::
tezos-client originate account alice_del for alice \
transfering 1000 from alice \
--delegate bob
As done before, we originate a contract *alice_del* with manager
*alice* and we fund it with 1kꜩ.
The interesting part is setting the delegate to *bob*, when
originating a contract the delegate is not set by default.
If you already own contracts that are delegatable you can change
the delegate with the command ``set delegate``.
Notice that only implicit accounts can be delegates, so your delegate
must by a *tz1* address.
Funds in implicit accounts which are not registered as delegates
do not participate in baking.
Running a delegate
------------------
We now explain how to run a delegate, which means running the 3
daemons for baking, endorsing and accusing.
In order to run a delegate you first need to register as one using
your implicit account:
::
tezos-client register key bob as delegate
Once registered, a delegate can participate in the network
proportionally to how many rolls it is delegated, that is
its own balance plus the balance of originated accounts and
contracts that are delegated to it.
Rolls
~~~~~
In the network, rights for baking and endorsing are randomly assigned
to delegates proportionally to the number of rolls they have been
delegated.
A roll is just a block of 10K tezzies.
To know when you will be allowed to bake in the current cycle, you
might try the following RPCs (use ``tezos-client list known
addresses`` to check the address of your account *bob*).
::
tezos-client rpc post /chains/main/blocks/head/helpers/rights/baking/delegate/tz1_xxxxxxxxxxx with {}
{ "ok":
[ { "level": 1400.000000, "priority": 2.000000,
"timestamp": "2017-05-19T03:21:52Z" },
... ] }
When you obtain Alphanet coins from :ref:`the faucet<faucet>`, if you
are lucky to obtain more than one roll, you can register a delegate
using this identity.
Otherwise, you need to ask the faucet for more accounts, orginate a
account for each one and delegate them to the first.
Deposits
~~~~~~~~
When baking or endorsing a block, a *security deposit* (or *bond*) is
frozen for ``preserved_cycles`` cycles from the account of the
delegate.
Hence a delegate must have enough funds to be able to pay security
deposits for all the blocks it can potentially bake/endorse during
``preserved_cycles``.
The current deposits are *512tz* for baked block and *64tz* for
endorsement.
Being delegated coins doesn't mean that a delegate can spend them,
they only add up to its rolls count.
All the deposits that are necessary to run the deamons can only be put
down from the delegate account.
Baker
~~~~~
The baker is a daemon that once connected to an account, computes the
baking rights for that account, collects transactions from the mempool
and bakes a block at priority zero.
Note that the baker is the only program that needs direct access to
the node data directory for performance reasons.
Let's launch the daemon pointing to the standard node directory and
baking for user *bob*:
::
tezos-baker-alpha run with local node ~/.tezos-node bob
Endorser
~~~~~~~~
The endorser is a daemon that once connected to an account, computes
the endorsing rights for that account and, upon reception of a new
block, verifies the validity of the block and emits an endorsement
operation.
It can endorse for a specific account or if omitted it endorses for
all accounts.
::
tezos-endorser-alpha run
Accuser
~~~~~~~
The accuser is a daemon that monitors all blocks received on all
chains and looks for:
* bakers who signed two blocks at the same level
* endorsers who injected more than one endorsement operation for the
same baking slot (more details :ref:`here<proof-of-stake>`)
Upon finding such irregularity, it will emit respectively a
double-baking or double-endorsing denunciation operation, which will
cause the offender to loose its security deposit.