balsoft/ligo
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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

Browse Source
This commit is contained in:
Marco Stronati 2018-07-20 23:43:28 +02:00
parent 8fb52eab6f
commit f626e9d6ae
10 changed files with 1224 additions and 1099 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
docs/index.rst
View File

@ -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
- 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 Alpha (test) network has been live and open since February 2017.
The source code of Tezos is placed under the MIT Open Source License.
The Tezos Beta (experimental) network has been live and open since June 2018.
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,25 +41,77 @@ 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 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>`.
The source code of Tezos is placed under the MIT Open Source License.
.. toctree::
:maxdepth: 2
:caption: Introduction:
introduction/howto
introduction/howtoget
introduction/howtouse
introduction/howtorun
introduction/various
introduction/contributing
.. toctree::
:maxdepth: 2
:caption: Test Networks:
introduction/alphanet
introduction/zeronet
.. toctree::
:maxdepth: 2
:caption: White doc:
@ -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

321
docs/introduction/alphanet.rst
View File

@ -1,321 +0,0 @@
.. _alphanet:
Alphanet
========
Welcome to the Tezos alphanet, which is a pre-release network for the
Tezos blockchain. Currently, the chain is reset every few weeks.
For news and support about the alphanet, please join IRC (*#tezos* on
freenode). Please, report bugs related to the alphanet on the IRC
channel before filling `GitLab issues
<https://gitlab.com/tezos/tezos/issues>`__.
For more information about the project in general, see:
https://tezos.com/
How to join the alphanet
------------------------
We provide two ways of joining the alphanet :
- an installation script that uses ``docker`` and prebuilt binaries
(recommended way, tested on windows/mac/linux, works on **x86_64**
architecture only),
- manual compilation and installation (linux and mac only).
The ``alphanet.sh`` script (x86_64 only)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The recommended way for running an up-to-date Tezos node connected to
the alphanet is to use ``scripts/alphanet.sh``. Its only requirement is
a working installation of `Docker <https://www.docker.com/>`__.
First, you need to download the script:
::
wget https://gitlab.com/tezos/tezos/raw/alphanet/scripts/alphanet.sh
chmod +x alphanet.sh
You are now one step away from a working node:
::
./alphanet.sh start
This will launch a docker container running the various daemons that
form a working tezos node. The first launch might take a few minutes to
synchronize the chain.
See ``./alphanet.sh --help`` for more informations about the script. In
particular see ``./alphanet.sh client --help`` and
``scripts/README.master`` for more information about the client.
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
Compilation from sources
~~~~~~~~~~~~~~~~~~~~~~~~
Please refer to the :ref:`instructions<howto>`.
For the rest of the document, to execute the example commands, you
will have to replace ``./alphanet.sh client`` by ``./tezos-client``.
How to observe the network
--------------------------
The alphanet script provides a basic command ``./alphanet.sh head`` that
allows you to see if your own node is synchronized.
The Tezos client also offers a lot of commands to introspect the state
of the node, and also to list and call the RPCs of the nodes.
Enthusiastic Tezos adopters have also developed some block
explorer for the alphanet. See for instance:
- https://ostez.com
- https://tzscan.io
- https://tezos.id
.. _faucet:
How to obtain free Tezzies
--------------------------
You must first grab a wallet from the `faucet
<https://faucet.tzalpha.net>`__.
This will provide you with a JSON file, named like
``tz1__xxxxxxxxx__.json``. Once your node is synchronized, you should
run the following command to activate your wallet, where ``my_account``
is a local name you choose, and ``tz1__xxxxxxxxx__.json`` is the name
of the file you grab:
::
$ tezos-client activate account "my_account" with "tz1__xxxxxxxxx__.json"
Operation successfully injected in the node.
Operation hash is 'ooGoVS5cikbTHEimTzYhQWrYqY2LeJYmfkbzoiW8KQ59jtGQaXr'.
Waiting for the operation to be included...
Operation found in block: BKihN2QgSAu2etftNvs8FWWhwTvZiY8P3e7H3jgdj2MCpKZXXRs
Account my_account (tz1__xxxxxxxxx__) created with ꜩ23,454.
Or, if you use the ``alphanet.sh`` script, you should prefix the file
with ``container:`` in order to copy it into the docker image:
::
$ ./alphanet.sh client activate account "my_account" with "container:tz1__xxxxxxxxx__.json"
You might check your balance with:
::
./alphanet.sh client get balance for "my_account"
Please preserve the JSON file, after each reset of the Alphanet, you
will have to reactivate the wallet. The same file might be use ta activate
an account on the Zeronet.
Please drink carefully and don't abuse the faucet: it only contains
30.000 wallets for a total amount of ꜩ760.000.000.
How to play with smart-contracts
--------------------------------
An advanced documentation of the smart contract language is available :ref:`here<michelson>`.
Some test contracts can be found in directory :src:`src/bin_client/test/contracts/`.
For details and examples, see also https://www.michelson-lang.com/
How to bake on the alphanet
---------------------------
Baking 101
~~~~~~~~~~
In order to understand how baking works, please refer to :ref:`this
section <proof-of-stake>`. The following is a **TL;DR** to help you
get started.
In Tezos there are two kinds of contracts: *implicit* and *originated*
accounts. Originated accounts can have michelson code, in which case
they are also called *contracts*.
- An *implicit account* is identified by a public key hash and is
automatically created when a public key hash is the recipient of a
transfer. The genesis block will contain one account per
contributor.
- An *originated account* or *contract* is *originated* with an
operation sent to the blockchain. It has a *manager* and an optional
*delegate* account.
The baking itself is done by *implicit accounts*. By default, they
don't participate in baking unless they are *registred* as
delegates. In order to register an *implicit account* as a delegate,
use:
::
./alphanet.sh client register key "my_account" as delegate
Once registered, an *implicit account* can participate in baking for
its own balance plus the balance of *originated accounts* and
*contracts* that are delegated to it.
Originated accounts and contracts thus participate in baking only via
their delegate. If they don't have a delegate set (the default, unless
you specify one), they don't participate in baking.
Implicit accounts cannot have a delegate. In order to delegate funds,
they need to be transfered to an *originated account* beforehand, and
a delegate must be set.
To summarize:
- *Implicit accounts* only can be registered as *delegates* and
actually bake.
- Funds in *implicit accounts* which are not registered as *delegates*
do not participate in baking.
- *Originated accounts* and *contracts* do not participate in baking
unless they have a delegate account set **and** this delegate is
actually baking.
In order to be entitled to bake, *delegates* need enough tezzies
(delegated or otherwise) to have a least one *roll*. Baking rights are
randomly chosen around rolls, which are blocks of 10K tezzies.
When you obtain Alphanet coins from :ref:`the faucet<faucet>`, if you
are lucky to obtain more than one roll, you can bake using this
identity (after it is registered as a delegate). Otherwise, you need
to ask the faucet for more coins. When you obtain more than 10K
tezzies into one or multiple identities, you are ready to start
baking!
Before we see how to bake with your delegate, you might want to know
how to delegate your tezzies. Although not necessary (you can just
bake with your delegate if it has enough tezzies), it is useful if you
want for example to avoid transfering all your coins in one
account.
Delegating your coins
~~~~~~~~~~~~~~~~~~~~~
As explained above, *implicit accounts* cannot have a delegate, so the
first step is to *originate* an *account* and transfer your tezzies
there. During the origination step, we will set the delegate.
::
./alphanet.sh client originate account <new> for <implicit> transfering <qty> from <implicit> --delegate <implicit>
Where ``<new>`` must be a contract alias that you choose,
``<implicit>`` is the alias of one *implicit account* that you own, and
``<qty>`` is the amount in tezzies that you want to transfer.
This will originate an *account*, transfer ``<qty>`` tezzies from
``<implicit>`` in it, and set that ``<implicit>`` is the manager and
the delegate for this freshly minted account.
If you already own contracts that are delegatable and want to change
the delegate to ``<implicit>``, use the following command:
::
./alphanet.sh client set delegate for <account> to <implicit>
You need to wait at most seven cycles which, on the Alphanet, is 7*128
blocks (something about 15 hours). On the mainnet, this will be around
3 weeks.
From now on, the funds in ``<new>`` will be delegated to
``<implicit>``. In the next section, we will learn how to bake with
your delegate.
Baking with your delegate
~~~~~~~~~~~~~~~~~~~~~~~~~
If you have read and followed the doc up until this point, you now
have a delegate, which have enough tezzies (delegated or otherwise) to
bake.
When baking or endorsing a block, a *security deposit* (or *bond*) is
taken out of the default account associated to the public key of the
delegate. Hence, in order to bake, your delegate must have enough
funds to be able to pay security deposits for baking and endorsing.
Check out the Alphanet *constants* for this:
::
./alphanet.sh client rpc get /blocks/head/proto/constants
Check for the ``endorsement_security_deposit`` and
``block_security_deposit`` keys of the JSON record. The value is in
*µtez*, one millionth of a tezzie. In the alphanet, the current value
is set to *512tz* per block and *64tz* per endorsement. If you run out
of funds, you will not be able to bake.
Now, you are settled. The ``alphanet`` docker image runs a baker
daemon and a endorser daemon, by default for all your keys.
To know if you baked, just run:
::
./alphanet.sh baker log
./alphanet.sh endorser log
You should see lines such as:
::
Injected block BLxzbB7PBW1axq for bootstrap5 after BLSrg4dXzL2aqq (level 1381, slot 0, fitness 00::0000000000005441, operations 21)
Or:
::
Injected endorsement for block 'BLSrg4dXzL2aqq' (level 1381, slot 3, contract bootstrap5) 'oo524wKiEWBoPD'
On the alphanet, rewards for staking are credited after 5 cycles (~10
hours). The reward for baking a block is ꜩ16 and ``ꜩ2 /
<block_priority>`` for endorsing a block. The safety bond is returned
together with the reward.
To know when you will be allowed to bake in the current cycle, you
might try the following RPCs, where you replaced ``tz1iFY8ads...`` by
the appropriate value:
::
$ ./alphanet.sh client list known addresses
my_account: tz1iFY8aDskx9QGbgBy68SNAGgkc7AE2iG9H (public key known) (secret key known)
$ ./alphanet.sh client rpc post /chains/main/blocks/head/helpers/rights/baking/delegate/tz1iFY8aDskx9QGbgBy68SNAGgkc7AE2iG9H with {}
{ "ok":
[ { "level": 1400.000000, "priority": 2.000000,
"timestamp": "2017-05-19T03:21:52Z" },
... ] }
.. include:: alphanet_changes.rst

254
docs/introduction/alphanet_changes.rst
View File

@ -1,254 +0,0 @@
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).

15
docs/introduction/contributing.rst
View File

@ -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
-----------

483
docs/introduction/howto.rst
View File

@ -1,483 +0,0 @@
.. _howto:
How to build and run
====================
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 at GitLab.
You also need to **choose a branch**:
- The *master* branch is where code is merged, but there is no test
network using the *master* branch directly.
- The *alphanet* and *alphanet-lmdb* is what you want to use if you want
to connect to Tezos' test network, the *Alphanet*. The
*-lmdb* version uses LMDB instead of LevelDB.
**TL;DR**: Typically you want to do:
::
git clone https://gitlab.com/tezos/tezos.git
git checkout alphanet
Install OPAM
------------
To compile Tezos, you need an OCaml compiler (version 4.06.1) and all
the libraries listed in the various ``tezos-*.opam`` files.
The simplest way to install all dependencies is by using `OPAM
<https://opam.ocaml.org/>`__, the OCaml package manager.
**IMPORTANT**: Please use `version 2
<https://opam.ocaml.org/blog/opam-2-0-0-rc3/>`_ of OPAM. That
is what the Tezos Core team uses. Most distribution probably ship
**version 1** of OPAM out of the box, but installing version 2 is
preferable for many reasons.
Install Tezos dependencies with OPAM
------------------------------------
Install the OCaml compiler and 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.
At last, compile the project:
::
make
This should produce several binaries:
- ``tezos-node``: the tezos daemon itself;
- ``tezos-client``: a command-line client;
- ``tezos-admin-client``: a command-line administration tool for the node;
- ``tezos-baker-alpha``: a client and daemon to bake on the Tezos network;
- ``tezos-endorser-alpha``: a client and daemon to bake on the Tezos network;
- ``tezos-accuser-alpha``: a client and daemon to bake on the Tezos network;
- ``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
macOS, but it has not been tested recently. A Windows port is feasible
and might be developed in the future.
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.
Join the Alphanet!
------------------
If you succesfully built Tezos on the *alphanet* or *alphanet-lmdb*
branch, then your node is elligible to join Tezos'
:ref:`Alphanet<alphanet>`.
Command-line basics
~~~~~~~~~~~~~~~~~~~
The `tezos-node` executable uses subcommands. You can obtain help on a
subcommand by using `./tezos-node <subcommand> --help`. There are
three subcommands:
::
./tezos-node identity --help
./tezos-node config --help
./tezos-node run --help
The `identity` and `config` serve the purpose of managing
configuration files for the node, we will describe them below. The
`run` command is for running the node.
Pretty much all configuration parameters can be overriden by a
command-line argument. Check out `./tezos-node run --help` to discover
them.
Configure your node
~~~~~~~~~~~~~~~~~~~
The following steps are required to connect to Alphanet.
::
./tezos-node identity generate
This will generate a new node identity and compute the associated
stamp of proof-of-work. The identity comprises a pair of cryptographic
keys that nodes use to encrypt messages sent to each other, and an
antispam-PoW stamp proving that enough computing power has been
dedicated to creating this identity.
The identity will be stored in `$HOME/.tezos-node/identity.json`.
::
./tezos-node config init
This will initialize an configuration file for the node in
`$HOME/.tezos-node/config.json`, using default values. It only
specifies that the node will listen to incoming connections on socket
address ``[::]:9732``.
The easiest way to amend this default configuration is to use
::
# Update the config file
./tezos-node config update <…>
# Start from an empty cfg file
./tezos-node config reset <…>
All blockchain data is stored under ``$HOME/.tezos-node/``. You can
change this by doing `./tezos-node config update --data-dir
</somewhere/in/your/disk>`.
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
the same ``data-dir``. Then run your node with `./tezos-node
run --config-file=</path/to/alternate_cfg>`.
Lastly, you want to enable RPC communication with clients. Use:
::
./tezos-node config update --rpc-addr=127.0.0.1:8732
This is the default socket address that the client will try, so
`./tezos-client` will work out-of-the-box that way.
Run your node
~~~~~~~~~~~~~
You are all set! Now you just need to do:
::
./tezos-node run
To interact with your node, read the doc of clients:
::
./tezos-client man
./tezos-admin-client man
./tezos-baker-alpha man
./tezos-signer man
And read :ref:`this section<faucet>` to learn how to get alphanet tezzies.
Use sandboxed mode
------------------
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``
Run a sandboxed node
~~~~~~~~~~~~~~~~~~~~
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
Use the sandboxed client
~~~~~~~~~~~~~~~~~~~~~~~~
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 get /chains/main/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 get /chains/main/blocks/head/metadata/next_protocol_hash
{ "protocol": "ProtoGenesisGenesisGenesisGenesisGenesisGenesk612im" }
$ tezos-activate-alpha
Injected BMBcK869jaHQDc
$ tezos-client rpc get /chains/main/blocks/head/metadata/next_protocol_hash
{ "protocol": "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK" }
Tune protocol alpha parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``tezos-active-alpha`` alias use parameters from
``scripts/protocol_parameters.json`` to activate protocol alpha. It can
be useful to tune these parameters when you need to debug something,
for example, change the number of blocks per cycle, the time between
blocks, etc.
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 node is in private mode or not. A node in
private mode only opens outgoing connections to peers whose
addresses are in [trusted_peers] and only accepts incoming
connections from trusted peers. In addition, it informs these
peers that the identity of the node should not be revealed to
the rest of the network. */
"private-mode": 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 bootstrapping /
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 independent 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 displayed 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 explicitly 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>`.

182
docs/introduction/howtoget.rst Normal file
View File

@ -0,0 +1,182 @@
.. _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

196
docs/introduction/howtorun.rst Normal file
View File

@ -0,0 +1,196 @@
.. _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.
::
tezos-accuser-alpha run
Remember that having two bakers or endorsers running connected to the
same account could lead to double baking/endorsing and the loss of all
your bonds.
If you are worried about availability of your node when is its turn to
bake/endorse there are other ways than duplicating your credentials.
**Never** use the same account on two daemons.
Rewards
~~~~~~~
After ``preserved_cycles``, not only the delegate takes back control of
its frozen deposits but it also receives the rewards for its hard work
which amount to 16ꜩ to bake a block and ``ꜩ2 / <block_priority>`` for
endorsing a block.
Docker
~~~~~~
The docker image runs the daemons by default for all your keys.
To know if you baked, just run:
::
./alphanet.sh baker log
./alphanet.sh endorser log
You should see lines such as:
::
Injected block BLxzbB7PBW1axq for bootstrap5 after BLSrg4dXzL2aqq (level 1381, slot 0, fitness 00::0000000000005441, operations 21)
Or:
::
Injected endorsement for block 'BLSrg4dXzL2aqq' (level 1381, slot 3, contract bootstrap5) 'oo524wKiEWBoPD'

467
docs/introduction/howtouse.rst Normal file
View File

@ -0,0 +1,467 @@
.. _howtouse:
How to use Tezos
================
This How To illustrates the use of the various Tezos binaries as well
as some concepts about the network.
The binaries
------------
After a successful compilation, you should have the following binaries:
- ``tezos-node``: the tezos daemon itself;
- ``tezos-client``: a command-line client and basic wallet;
- ``tezos-admin-client``: administration tool for the node;
- ``tezos-{baker,endorser,accuser}-alpha``: daemons to bake, endorse
and accuse on the Tezos network (see :ref:`howtorun`);
- ``tezos-signer``: a client to remotely sign operations or blocks
(see :ref:`signer`);
- ``tezos-protocol-compiler``: a protocol compiler used for developing
new version of the economic protocol.
Read The Friendly Manual
------------------------
The manual of each binary can be obtained with the command ``man`` and
the verbosity can be increased with ``-v``.
To use one specific command, type the command without arguments to see
possible completions and options.
It is also possible to search a keyword in the manual with ``man
keyword``.
The full documentation is also available online :ref:`client_manual`.
::
tezos-client man -v 3
tezos-client transfer
tezos-client man set
Node
----
The node is effectively the Tezos block-chain and it has two main
functions: running the gossip network and the updating the context.
The gossip network is where all Tezos nodes exchange blocks and
operations with each other (see :ref:`tezos-admin-client` to monitor
p2p connections).
Using this peer-to-peer network an operation originated by a user, can
hop several times through other nodes until it finds its way in a
block baked by a baker.
Using the blocks it receives on the gossip network the shell also
keeps up to date the current `context`, that is the full state of
the block-chain shared by all peers.
Approximately every minute a new block is created and, when the shell
receives it, it applies each operation in the block to its current
context and computes a new context.
The last block received on a chain is also called the `head` of that
chain.
Each new head is then advertised by the node to its peers,
disseminating this information to build a consensus across the
network.
Other than passively observing the network, your node can also inject
its own new operations when instructed by the ``tezos-client`` and even
send new blocks when guided by the ``tezos-baker-alpha``.
The node has also a view of the multiple chains that may exist
concurrently and selects the best one based on its fitness (see
:ref:`proof-of-stake`).
Node identity
~~~~~~~~~~~~~
First we need to generate a new identity in order for the node to
connect to the network:
::
tezos-node identity generate
The identity comprises a pair of cryptographic
keys that nodes use to encrypt messages sent to each other, and an
antispam-PoW stamp proving that enough computing power has been
dedicated to creating this identity.
Note that this is merely a network identity and it is not related in
any way to a Tezos address on the block-chain.
Storage
~~~~~~~
All block-chain data is stored under ``$HOME/.tezos-node/``.
If for some reason your node is misbehaving or there has been an
upgrade of the network, it is safe to remove this directory, it just
means that your node will take some time to resync the chain.
You can keep ``identity.json`` if it takes a long time for you to
compute it and only remove the ``store`` and ``context`` directories.
If you are also running a baker make sure that it has access to the
``.tezos-node`` directory of the node.
RPC interface
~~~~~~~~~~~~~
The only interface to the node is through Json RPC calls and it is disabled by
default. A more detailed documentation can be found in the :ref:`RPC index.
<rpc>` The RPC interface must be enable in order for the clients
to communicate with the node, but is should not be publically accessible on the
internet. With the following command it is available uniquely on the
`localhost` address of your machine.
::
tezos-node run --rpc-addr [::]
You can read more about the :ref:`node configuration <node-conf>` and
its :ref:`private mode <private-mode>`.
Client
------
Tezos client can be used to interact with the node, it can query its
status or ask the node to perform some actions.
For example after starting your node you can check if it has finished
synchronizing using
::
tezos-client bootstrapped
This call will hang and return only when the node is synchronized.
We can now check what is the current timestamp of the head of the
chain (time is in UTC so it may differ from your local):
::
tezos-client get timestamp
A simple wallet
~~~~~~~~~~~~~~~
The client is also a basic wallet and after the activation above you
will notice that the directory ``.tezos-client`` has been populated with
3 files ``public_key_hashs``, ``public_keys`` and ``secret_keys``.
The content of each file is in json and keeps the mapping between
aliases (``alice`` in our case) and what you would expect from the name
of the file.
Secret keys are stored on disk encrypted with a password except when
using a hardware wallet (see :ref:`ledger`).
An additional file ``contracts`` contains the addresses of `originated
contracts`, which have the form *KT1…*.
We can for example generate a new pair of keys, which can used locally
with the alias *bob*:
::
$ tezos-client gen keys bob
Tezos support three different ECC schemes: *Ed25519*, *secp256k1* (the
one used in Bitcoin), and *P-256* (also called *secp256r1*). The two
latter curves have been added for interoperability with Bitcoin and
Hardware Security Modules (*HSMs*) mostly. Unless your use case
require those, you should probably use *Ed25519*. We use a verified
library for Ed25519, and it is generally recommended over other curves
by the crypto community, for performance and security reasons.
Make sure to make a back-up of this directory and that the password
protecting your secret keys is properly managed.
For more advanced key management we offer :ref:`ledger support
<ledger>` and a :ref:`remote signer<signer>`.
.. _faucet:
Get free Tezzies
~~~~~~~~~~~~~~~~
In order to test the networks and help users get familiar with the
system, on Zeronet and Alphanet you can obtain free Tezzies from a
`faucet <https://faucet.tzalpha.net>`__.
This will provide a wallet in the form of a JSON file
``tz1__xxxxxxxxx__.json``, that can be activated with the following
command:
::
tezos-client activate account alice with "tz1__xxxxxxxxx__.json"
If you use the ``alphanet.sh`` script, you should prefix the file
with ``container:`` in order to copy it into the docker image:
``./alphanet.sh client activate account alice with "container:tz1__xxxxxxxxx__.json"``
Let's check the balance of the new account with:
::
tezos-client get balance for alice
Please preserve the JSON file, after each reset of Zeronet or
Alphanet, you will have to reactivate the wallet.
Please drink carefully and don't abuse the faucet: it only contains
30.000 wallets for a total amount of ꜩ760.000.000.
Transactions
~~~~~~~~~~~~
Let's transfer some tezzies to the new account:
::
tezos-client transfer 1 from alice to bob --fee 0.05
The ``transfer`` command returns a receipt with all the details of the
transaction, including its hash, and then waits for the operation to
be included in one block.
If you want to simulate a transaction without actually sending it to
the network you can use the ``--dry-run`` option.
As in any block-chain it is advisable to wait several blocks to
consider the transaction as final, we can do that with:
::
tezos-client wait for <operation hash> to be included
Receipts for operations and blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After an operation the client prints a `receipt` that recapitulates
the effects of the operation on the block-chain.
It is possible to review the receipt of a transaction with:
::
tezos-client rpc get /chains/main/blocks/head/operations
A manager operation, such as a transaction, has 3 important
parameters: counter, gas and storage limit.
The counter belongs to each account, it increases at each operation
signed by that account and enforces some good intuitive properties:
- each operation is unique: for example if we perform twice the same
transfer from *alice* to *bob*, even if all the data are the
same the counter will be different.
- each operation is applied once: for example if the transfer above
reaches two peers and they both send it to a third peer, it will not
apply the transaction twice.
- operations are applied in order: if we emit a transaction towards
*bob* and a transaction from *bob* to *test3*, we can be sure
that the second transaction will be applied only after *bob*
received its funds otherwise it may fail for insufficient balance.
- all previous operations have been applied: if we emit operation *n*
and *n+1*, and *n* gets lost then *n+1* cannot be applied.
Additionally each operation needs to declare a gas and storage limit,
if an operations consumes more than this limits it will fail.
Later we'll learn more about the gas and storage model.
Another interesting field of the receipts are the `balance updates`
showing which account was credited or debited.
For the transaction above the updates are symmetrical, *alice* is
debited 1ꜩ and *bob* is credited the same amount.
The same is true for the fees with the difference that the baker is
credited and, more importantly, it is not credited immediately on its
main account but on its frozen fees account, hence the category
`freezer`.
Each delegate has 3 frozen accounts: `deposits`, `fees` and `rewards`.
They are frozen because the delegate can't use them for now, but only
after a number cycles.
It is also possible to review the receipt of the whole block:
::
tezos-client rpc get /chains/main/blocks/head/metadata
Here we always see the deposit that the baker had to put down to bake
the block, which is again a debit on its main account paired with a
credit on its `deposits` account, and the creation of a reward, which
is a single credit to its `rewards` account.
An interesting block receipt is the one produced at the end of a
cycle as many delegates receive back part of their unfrozen accounts.
.. _originated_accounts:
Originated accounts and Contracts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In Tezos there are two kinds of accounts: *implicit* and *originated*.
The implicit accounts are the *tz1* we have used up to now and to
create them if suffices to have a pair of keys and to transfer some
funds to the public key hash.
Originated accounts have addresses *KT1* and are created through an
origination operation.
One reason to originate an account is to delegate your tokens
(see more :ref:`here. <howtorun>`).
The other main reason is that an originated account can also have
Michelson code, in which case it is called a *contract*.
Let's originate our first contract and call it *id*:
::
tezos-client originate contract id for alice \
transferring 1 from alice \
running ./src/bin_client/test/contracts/id.tz \
--init '"hello"'
We set *alice* as manager, a 1ꜩ starting balance generously provided
by *alice* and the code from the ``id.tz`` Michelson program which
is just the identity.
Every program declares in its first 2 lines the type of its parameter
and storage, for *id* they are both strings so we initialize the
contract with the string ``"hello"`` (the extra quotes are to avoid
the shell expansion).
Gas and storage cost model
~~~~~~~~~~~~~~~~~~~~~~~~~~
A quick look at the balance updates on the receipt shows that on top of
funding the contract with 1ꜩ, *alice* was also charged an extra cost
that is burnt.
This cost comes from the *storage* and it's shown in the line
``Paid storage size diff: 46 bytes``, 41 for the contract and 5 for
the string ``"hello"``.
Given that a contract saves it's data on the public block-chain that
every node stores, it is necessary to charge a fee per byte to avoid
abuse and encourage lean programs.
Let's see what calling a program with a new argument would look like
with the ``--dry-run`` option:
::
tezos-client transfer 0 from alice to id --arg '"world"' --dry-run
The transaction would successfully update the storage but this time it
wouldn't cost us anything more than the fee, the reason is that the
storage for ``"world"`` is the same as for ``"hello"``, which has
already been paid for.
To store more we'll need to pay more, you can try by passing a longer
string.
The other cost associated with running contracts is the *gas*, which
measures *how long* does a program take to compute.
Contrary to storage there is no cost per gas unit, a transfer can
require as much gas as it wants, however a baker that has to choose
among several transactions is much more likely to include a low gas
one because it's cheaper to run and validate.
At the same time bakers also give priority to high fee transactions.
This means that there is an implicit cost for gas that is related to
the fee offered versus the gas and fees of other transactions.
If you are happy with the gas and storage of your transaction you can
run it for real, however it is always a good idea to set explicit
limit for both. The transaction fails if the limits are passed.
::
tezos-client transfer 0 from alice to id --arg '"world"' \
--gas-limit 1475 \
--storage-limit 46
A baker is more likely to include an operation with lower gas and
storage limits because it takes less resources to execute so it is in
the best interest of the user to pick limits that are as close as
possible to the actual use.
More test contracts can be found in directory
:src:`src/bin_client/test/contracts/`.
An advanced documentation of the smart contract language is available
:ref:`here<michelson>`.
For details and examples, see also https://www.michelson-lang.com/
Validation
~~~~~~~~~~
The node allows to validate an operation before submitting it to the
network by simply simulating the application of the operation to the
current context.
In general if you just send an invalid operation e.g. sending more
tokens that what you own, the node will broadcast it and when it is
included in a block you'll have to pay the usual fee even if it won't
have an affect on the context.
To avoid this case the client first asks the node to validate the
transaction and then sends it.
The same validation is used when you pass the option ``--dry-run``,
the receipt that you see is actually a simulated one.
Another important use of validation is to determine gas and storage
limits.
The node first simulates the execution of a Michelson program and
takes trace of the amount of gas and storage.
Then the client sends the transaction with the right limits for gas
and storage based on that indicated by the node.
This is why we were able to submit transactions without specifying
this limits, they were computed for us.
More information on validation can be found :ref:`here. <validation>`
It's RPCs all the way down
~~~~~~~~~~~~~~~~~~~~~~~~~~
The client communicates with the node uniquely through RPC calls so
make sure that the node is listening and that the ports are
correct.
For example the ``bootstrapped`` command above is a shortcut for:
::
tezos-client rpc get /monitor/bootstrapped
The client tries to simplify common tasks as much as possible, however
if you want to query the node for more specific informations you'll
have to resort to RPCs.
For example to check the value of important constants in Tezos, which
may differ between Betanet, Alphanet and Zeronet, you can use:
::
tezos-client rpc get /chains/main/blocks/head/context/constants | jq
{
"proof_of_work_nonce_size": 8,
"nonce_length": 32,
"max_revelations_per_block": 32,
"max_operation_data_length": 16384,
"preserved_cycles": 5,
"blocks_per_cycle": 4096,
"blocks_per_commitment": 32,
"blocks_per_roll_snapshot": 256,
"blocks_per_voting_period": 32768,
"time_between_blocks": [
"60",
"75"
],
"endorsers_per_block": 32,
"hard_gas_limit_per_operation": "400000",
"hard_gas_limit_per_block": "4000000",
"proof_of_work_threshold": "70368744177663",
"tokens_per_roll": "10000000000",
"michelson_maximum_type_size": 1000,
"seed_nonce_revelation_tip": "125000",
"origination_burn": "257000",
"block_security_deposit": "48000000",
"endorsement_security_deposit": "6000000",
"block_reward": "0",
"endorsement_reward": "0",
"cost_per_byte": "1000",
"hard_storage_limit_per_operation": "60000"
}
You can find more info in the :ref:`RPCs' page. <rpc>`

286
docs/introduction/various.rst Normal file
View File

@ -0,0 +1,286 @@
Various
=======
.. _tezos-admin-client:
Admin Client
------------
The admin client gives access to more commands to interact with the
peer-to-peer layer in order to:
- check the status of the connections
- force connections to known peers
- ban/unban peers
A useful command to debug a node that is not syncing is:
::
tezos-admin-client p2p stat
Use sandboxed mode
------------------
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``
Run a sandboxed node
~~~~~~~~~~~~~~~~~~~~
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 --connections 1
This node will store its data in a temporary directory
``/tmp/tezos-node.xxxxxxxx`` which will be removed when the node is
stopped.
The option ``--connections`` is just to remove the spurious “Too few
connections” warnings by lowering the number of expected connection.
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 --connections 1
You might replace ``1`` or ``9`` by any number in between if you want to
run more than two nodes.
Use the sandboxed client
~~~~~~~~~~~~~~~~~~~~~~~~
Once your node is running, open a new terminal and initialize the
“sandboxed” client data in a temporary directory:
::
eval `./src/bin_client/tezos-init-sandboxed-client.sh 1`
It also define in the current shell session an alias ``tezos-client``
preconfigured for communicating with the same-numbered node.
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 get /chains/main/blocks/head/metadata
"next_protocol": "Ps9mPmXaRzmzk35gbAYNCAw6UXdE2qoABTHbN2oEEc1qM7CwT9P"
$ tezos-activate-alpha
Injected BMV9KnSPE1yw
$ tezos-client rpc get /chains/main/blocks/head/metadata/next_protocol_hash
"protocol": "Ps9mPmXaRzmzk35gbAYNCAw6UXdE2qoABTHbN2oEEc1qM7CwT9P"
Tune protocol alpha parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``tezos-active-alpha`` alias use parameters from
``scripts/protocol_parameters.json`` to activate protocol alpha. It can
be useful to tune these parameters when you need to debug something,
for example, change the number of blocks per cycle, the time between
blocks, etc.
.. _node-conf:
Configuration options for the node
----------------------------------
::
./tezos-node config init
This will initialize a configuration file for the node in
`$HOME/.tezos-node/config.json`, using default values. It only
specifies that the node will listen to incoming connections on socket
address ``[::]:9732``.
The easiest way to amend this default configuration is to use
::
# Update the config file
./tezos-node config update <…>
# Start from an empty cfg file
./tezos-node config reset <…>
All blockchain data is stored under ``$HOME/.tezos-node/``. You can
change this by doing `./tezos-node config update --data-dir
</somewhere/in/your/disk>`.
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
the same ``data-dir``. Then run your node with `./tezos-node
run --config-file=</path/to/alternate_cfg>`.
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 node is in private mode or not. A node in
private mode only opens outgoing connections to peers whose
addresses are in [trusted_peers] and only accepts incoming
connections from trusted peers. In addition, it informs these
peers that the identity of the node should not be revealed to
the rest of the network. */
"private-mode": 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 bootstrapping /
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 independent 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 displayed by `tezos-node run –-help`.

18
docs/introduction/zeronet.rst
View File

@ -1,18 +0,0 @@
.. _zeronet:
Zeronet
=======
Zeronet is the most cutting-edge development network of Tezos. It is
restarted without notice, possibly several times a day.
If you wish to experiment with Tezos we recommend you to test
:ref:`Alphanet<alphanet>`, which is a more stable test network. We
offer no support about the zeronet.
Otherwise, the instructions to use Zeronet are the same as Alphanet,
except that ``alphanet.sh`` is replaced with ``zeronet.sh`` if you use
Docker.
You need to use the same faucet (see :ref:`faucet`) to get and
activate your wallet.