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

2018-07-20 23:43:28 +02:00 · 2018-07-20 23:43:28 +02:00 · f626e9d6ae
commit f626e9d6ae
parent 8fb52eab6f
10 changed files with 1224 additions and 1099 deletions
--- a/docs/index.rst
+++ b/docs/index.rst
@ -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
+ - Developer documentation is available online at https://tezos.gitlab.io/master
-   always in sync with the master branch (which may be desynchronized with
+   The documentation is automatically generated for the master branch and the
-   the code running on the live networks, replace ``master`` in the URL by the
+   three official network branches `betanet <https://tezos.gitlab.io/betanet>`_,
-   branch of your choice: betanet, alphanet, zeronet, to make sure you are
+   `alphanet <https://tezos.gitlab.io/alphanet>`_,
-   consulting the right API version)
+   `zeronet <https://tezos.gitlab.io/zeronet>`_. Make sure you are
- - The official Tezos website https://tezos.com/ contains more information about the
+   consulting the right API version.
-   project.
+ - The website https://tezos.com/ contains more information about the project.
- - All development now happens on GitLab at https://gitlab.com/tezos/tezos
+ - 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
--- a/docs/introduction/alphanet.rst
+++ b/docs/introduction/alphanet.rst
@ -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
--- a/docs/introduction/alphanet_changes.rst
+++ b/docs/introduction/alphanet_changes.rst
@ -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).
--- a/docs/introduction/contributing.rst
+++ b/docs/introduction/contributing.rst
@ -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
 -----------
--- a/docs/introduction/howto.rst
+++ b/docs/introduction/howto.rst
@ -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>`.
--- a/docs/introduction/howtoget.rst
+++ b/docs/introduction/howtoget.rst
@ -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
--- a/docs/introduction/howtorun.rst
+++ b/docs/introduction/howtorun.rst
@ -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'
--- a/docs/introduction/howtouse.rst
+++ b/docs/introduction/howtouse.rst
@ -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>`
--- a/docs/introduction/various.rst
+++ b/docs/introduction/various.rst
@ -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`.
--- a/docs/introduction/zeronet.rst
+++ b/docs/introduction/zeronet.rst
@ -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.