From 93bafba9ef5b575c3c6f921297770627c1d53bdf Mon Sep 17 00:00:00 2001 From: Marco Stronati Date: Wed, 1 Aug 2018 17:13:54 +0200 Subject: [PATCH] Doc: small improvements and fixes --- docs/index.rst | 43 +++++++++++++++++++--------------- docs/introduction/howtoget.rst | 19 ++++++++------- docs/introduction/howtouse.rst | 36 +++++++++++++++++++--------- 3 files changed, 60 insertions(+), 38 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 42f1e0865..e84c74680 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -49,6 +49,26 @@ The Community The Networks ------------ +.. _betanet: + +Betanet +~~~~~~~ + +The Tezos Beta (experimental) network is the current incarnation of +the Tezos blockchain. +It runs with 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 +`_. + +The Tezos Beta (experimental) network has been live and open since +`June 30th 2018 `_. + +All the instructions in this documentation are valid for Betanet +however we **strongly** encourage users to first try all the +introduction tutorials on Alphanet to familiarize themselves without +risks. + .. _alphanet: Alphanet @@ -56,8 +76,8 @@ 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 updated and rebooted rarely and it is running the same code as +the Betanet. 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. @@ -75,26 +95,11 @@ 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. +have *different constants* that Alphanet or Betanet, for example it +has shorter cycles and a shorter interval between blocks. 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 -`_. - -The Tezos Beta (experimental) network has been live and open since -`June 30th 2018 `_. - - Getting started --------------- diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst index 4d9b7a924..263b4bf84 100644 --- a/docs/introduction/howtoget.rst +++ b/docs/introduction/howtoget.rst @@ -24,8 +24,9 @@ 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. +The same script can be used to run Alphanet, Betanet or Zeronet, it +suffices to rename it as it downloads a different image based on its +name. For example, to run Alphanet: :: @@ -33,15 +34,14 @@ For example, to run Alphanet: wget https://gitlab.com/tezos/tezos/raw/master/scripts/alphanet.sh chmod +x alphanet.sh -Alternatively, to run Zeronet: +Alternatively, to run Betanet: :: - wget -O zeronet.sh https://gitlab.com/tezos/tezos/raw/master/scripts/alphanet.sh - chmod +x zeronet.sh + wget -O betanet.sh https://gitlab.com/tezos/tezos/raw/master/scripts/alphanet.sh + chmod +x betanet.sh In the following we assume you are running Alphanet. - You are now one step away from a working node: :: @@ -83,7 +83,7 @@ Build from sources :: - sudo apt install -y git m4 build-essential patch unzip bubblewrap wget + sudo apt install -y rsync 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 @@ -113,6 +113,8 @@ The following OSes are reported to work: A Windows port is feasible and might be developed in the future. +If ``bubblewrap`` is not available in your distribution you can also +skip it and init opam with ``--disable-sandbox``. Get the sources ~~~~~~~~~~~~~~~ @@ -179,4 +181,5 @@ 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 + + opam repo add default --rank=-1 diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index cadca93c8..f61d24ef0 100644 --- a/docs/introduction/howtouse.rst +++ b/docs/introduction/howtouse.rst @@ -18,8 +18,13 @@ After a successful compilation, you should have the following binaries: 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. + +Note that Alphanet and Zeronet only support the last version of the +protocol which is always called `alpha` while Betanet must also +support all past protocols. +For this reason the name of the 3 daemons in Betanet contains the +incremental number and the partial hash of the protocol they are bound +to, such as ``tezos-{baker,endorser,accuser}-002-PsYLVpVv``. Read The Friendly Manual @@ -111,12 +116,14 @@ default. A more detailed documentation can be found in the :ref:`RPC index. ` 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. +`localhost` address of your machine, on the default port ``8732``. :: - tezos-node run --rpc-addr [::] + tezos-node run --rpc-addr 127.0.0.1 +The node listens by default on port ``19732`` so it is advisable to +open incoming connections to that port. You can read more about the :ref:`node configuration ` and its :ref:`private mode `. @@ -227,12 +234,22 @@ 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: +consider the transaction as final, for an important operation we +advice to wait 60 blocks. +We can do that with: :: tezos-client wait for to be included +In the rare case when an operation is lost, how can we be sure that it +will not be included in any future block and re-emit it? +After 60 blocks a transaction is considered invalid and can't be +included anymore in a block. +Furthermore each operation has a counter (explained in more detail +later) that prevents replays so it is usually safe to re-emit an +operation that seems lost. + Receipts for operations and blocks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -256,10 +273,7 @@ signed by that account and enforces some good intuitive properties: - 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. +- operations are applied in order. - all previous operations have been applied: if we emit operation *n* and *n+1*, and *n* gets lost then *n+1* cannot be applied. @@ -419,11 +433,11 @@ 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: +For example the ``get timestamp`` command above is a shortcut for: :: - tezos-client rpc get /monitor/bootstrapped + tezos-client rpc get /chains/main/blocks/head/header/shell 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