From f626e9d6ae7d83c6f6f4af2cfeb3a84b17dfcd28 Mon Sep 17 00:00:00 2001 From: Marco Stronati Date: Fri, 20 Jul 2018 23:43:28 +0200 Subject: [PATCH] Doc: new introduction howto{get,use,run} --- docs/index.rst | 101 ++++-- docs/introduction/alphanet.rst | 321 ---------------- docs/introduction/alphanet_changes.rst | 254 ------------- docs/introduction/contributing.rst | 15 + docs/introduction/howto.rst | 483 ------------------------- docs/introduction/howtoget.rst | 182 ++++++++++ docs/introduction/howtorun.rst | 196 ++++++++++ docs/introduction/howtouse.rst | 467 ++++++++++++++++++++++++ docs/introduction/various.rst | 286 +++++++++++++++ docs/introduction/zeronet.rst | 18 - 10 files changed, 1224 insertions(+), 1099 deletions(-) delete mode 100644 docs/introduction/alphanet.rst delete mode 100644 docs/introduction/alphanet_changes.rst delete mode 100644 docs/introduction/howto.rst create mode 100644 docs/introduction/howtoget.rst create mode 100644 docs/introduction/howtorun.rst create mode 100644 docs/introduction/howtouse.rst create mode 100644 docs/introduction/various.rst delete mode 100644 docs/introduction/zeronet.rst diff --git a/docs/index.rst b/docs/index.rst index f3285fbf6..42f1e0865 100644 --- 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 - 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 `_, + `alphanet `_, + `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 `. - 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 `_. - - 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 +`_. + +The Tezos Beta (experimental) network has been live and open since +`June 30th 2018 `_. + + +Getting started +--------------- + +The best place to start exploring the project is following the How Tos +in the :ref:`introduction `. -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 diff --git a/docs/introduction/alphanet.rst b/docs/introduction/alphanet.rst deleted file mode 100644 index 2b8177849..000000000 --- a/docs/introduction/alphanet.rst +++ /dev/null @@ -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 -`__. - -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 `__. - -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`. - -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 -`__. - -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`. - -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 `. 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`, 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 for transfering from --delegate - - -Where ```` must be a contract alias that you choose, -```` is the alias of one *implicit account* that you own, and -```` is the amount in tezzies that you want to transfer. - -This will originate an *account*, transfer ```` tezzies from -```` in it, and set that ```` 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 ````, use the following command: - -:: - - ./alphanet.sh client set delegate for to - - -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 ```` will be delegated to -````. 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 / -`` 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 diff --git a/docs/introduction/alphanet_changes.rst b/docs/introduction/alphanet_changes.rst deleted file mode 100644 index 9e2abd212..000000000 --- a/docs/introduction/alphanet_changes.rst +++ /dev/null @@ -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). diff --git a/docs/introduction/contributing.rst b/docs/introduction/contributing.rst index abcfc901e..483dfd36b 100644 --- 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 `__. +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 ----------- diff --git a/docs/introduction/howto.rst b/docs/introduction/howto.rst deleted file mode 100644 index e4301b0bd..000000000 --- a/docs/introduction/howto.rst +++ /dev/null @@ -1,483 +0,0 @@ -.. _howto: - -How to build and run -==================== - -Get the sources ---------------- - -Tezos *git* repository is hosted at `GitLab -`_. All development happens here. Do -**not** use our `GitHub mirror `_ -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 -`__, the OCaml package manager. - - -**IMPORTANT**: Please use `version 2 -`_ 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`. - -Command-line basics -~~~~~~~~~~~~~~~~~~~ - -The `tezos-node` executable uses subcommands. You can obtain help on a -subcommand by using `./tezos-node --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 -`. - -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=`. - -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` 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` and -:ref:`here`. diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst new file mode 100644 index 000000000..4d9b7a924 --- /dev/null +++ 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 +`_. +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 +`__ 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` 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 +`_. All development happens here. Do +**not** use our `GitHub mirror `_ +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 `__ +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 diff --git a/docs/introduction/howtorun.rst b/docs/introduction/howtorun.rst new file mode 100644 index 000000000..3f12b537b --- /dev/null +++ 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 `. + + +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`, 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`) + +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 / `` 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' diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst new file mode 100644 index 000000000..cadca93c8 --- /dev/null +++ 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. +` 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 ` and +its :ref:`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 +` and a :ref:`remote 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 `__. + +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 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. `). +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`. +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. ` + +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. ` diff --git a/docs/introduction/various.rst b/docs/introduction/various.rst new file mode 100644 index 000000000..d629e497d --- /dev/null +++ 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 +`. + +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=`. + +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`. diff --git a/docs/introduction/zeronet.rst b/docs/introduction/zeronet.rst deleted file mode 100644 index d83b962f4..000000000 --- a/docs/introduction/zeronet.rst +++ /dev/null @@ -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`, 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.