diff --git a/docs/introduction/howtorun.rst b/docs/introduction/howtorun.rst index 71cd282ff172eff8063af2fde47754b335321f77..89b07b37dbf1df1c73965b353ac0c872b79a8472 100644 --- a/docs/introduction/howtorun.rst +++ b/docs/introduction/howtorun.rst @@ -3,7 +3,7 @@ How to run Tezos ================ -In this section we discuss how to take part in the protocol that runs +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. @@ -97,7 +97,7 @@ come from the delegate's account. If a delegate runs out of funds to deposit it won't be able to bake or endorse. Other than being a missed opportunity for them, this has also negative consequences on the network. -Missing baking slots slows the network, as it is necessary to wait one +Missing baking slots slows the network, as it is necessary to wait for one minute for the baker at priority 2 to bake, while missing endorsements reduce the fitness of the chain, making it more susceptible to forks. Running out of funds can happen if a delegate is *over-delegated*, @@ -113,16 +113,16 @@ Expected rights, deposits and rewards ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Let's assume we have 1 roll, we want to estimate our chances to bake -or endorse in order to prepare the funds for our deposits. +or endorse to prepare the funds for our deposits. Our chances depend on how many rolls are currently active in the network, once we know that we can estimate how many blocks and endorsements we could be assigned in a cycle. -The number of active rolls can be computed with two RPCs, first we -list all the active delegates with ``delegates?active``, then we sum -all their ``stacking_balance`` and we simply divide by the size of a +The number of active rolls can be computed with two RPCs. First, we +list all the active delegates with ``delegates?active``. Then, we sum +all their ``stacking_balance``. Finally, we simply divide by the size of a roll, 8kꜩ. At the time of writing, on Betanet the number of active rolls is ~30k -so for each block we know that the chance that we get selected for +so for each block, we know that the chance that we get selected for baking is ``1/30k`` while for endorsing is 32 times that. Given that every draw is with replacement, the distribution that describes our chances of being selected is the binomial with @@ -133,10 +133,10 @@ we draw, in our case in a cycle the draws for baking are ``n_b = Moreover we could extend ``n`` to cover ``preserved_cycles = 5``. Once we have ``p`` and ``n``, the expected number of times that we might get selected is ``p * n`` (the mean of the distribution). -Over many cycles our chances will fall around the mean, in some cycles +Over many cycles, our chances will fall around the mean, in some cycles, we might get unlucky and be assigned fewer rights, but in some cycles we might get lucky and be assigned more rights! -Clearly we would like to plan ahead and have enough deposits to cover +Clearly, we would like to plan and have enough deposits to cover also the "lucky" cycles so we need to compute a sort of "maximum" number of rights that is safe for `most cases`. We can compute this maximum using the inverse of Cumulative @@ -145,7 +145,7 @@ confidence that we can put to 95%. There a simple `Python script `_ that does the computation for us and returns the deposits and rewards, -expected and maximum, for a cycle and for `preserved_cycles`. +expected and maximum, for a cycle and `preserved_cycles`. :: @@ -178,15 +178,15 @@ expected and maximum, for a cycle and for `preserved_cycles`. mean 10.92 + 43.69 max 32.00 + 60.00 -As a rule of thumb if we want to have a very high confidence that we +As a rule of thumb if we want to have very high confidence that we won't miss any opportunity we should have around ~3kꜩ for deposits, -on the other hand the expected returns will probably be around ~10ꜩ per cycle. +on the other hand, the expected returns will probably be around ~10ꜩ per cycle. After ``preserved_cycles``, not only does the delegate take 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. -Additionally a baker also receives the fees of the operations it +Additionally, a baker also receives the fees of the operations it included in its blocks. While fees are unfrozen after ``preserved_cycles`` like deposits and rewards, they participate in the staking balance of the delegate @@ -198,7 +198,7 @@ immediately after the block has been baked. Register and check your rights ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In order to run a delegate you first need to register as one using +To run a delegate, you first need to register as one using your implicit account:: tezos-client register key bob as delegate @@ -234,7 +234,7 @@ it simply by re-registering again like above. Baker ~~~~~ -The baker is a daemon that once connected to an account, computes the +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. Note that the baker is the only program that needs direct access to @@ -248,7 +248,7 @@ baking for user *bob*:: Endorser ~~~~~~~~ -The endorser is a daemon that once connected to an account, computes +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. @@ -271,7 +271,7 @@ chains and looks for: 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. +cause the offender to lose its security deposit. :: @@ -280,7 +280,7 @@ cause the offender to loose its security deposit. 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 it is its turn to +If you are worried about the availability of your node when it is its turn to bake/endorse, there are other ways than duplicating your credentials. **Never** use the same account on two daemons. diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index ee355da321460bc32355a6e0a1649c087a584b1b..601d8449c8b7b77cb840137b5d15b9ed1965664d 100644 --- a/docs/introduction/howtouse.rst +++ b/docs/introduction/howtouse.rst @@ -76,7 +76,7 @@ concurrently and selects the best one based on its fitness (see Node Identity ~~~~~~~~~~~~~ -First we need to generate a new identity in order for the node to +First, we need to generate a new identity for the node to connect to the network:: tezos-node identity generate @@ -96,7 +96,7 @@ Node Synchronization Whenever a node starts, it tries to retrieve the most current head of the chain from its peers. This can be a long process if there are many blocks to retrieve -(e.g. when a node is launched for the first time, or has been out of sync for a +(e.g. when a node is launched for the first time or has been out of sync for a while), or on a slow network connection. The mechanism of :ref:`snapshots` can help in reducing the synchronization time. @@ -134,7 +134,7 @@ If removing this directory, please note that if it took you a long time to compute your node identity, keep the ``identity.json`` file and instead only remove the child ``store`` and ``context`` directories. -If you are also running a baker make sure that it has access to the +If you are also running a baker, make sure that it has access to the ``.tezos-node`` directory of the node. @@ -142,10 +142,10 @@ 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 enabled in order for the clients -to communicate with the node, but is should not be publicly accessible on the -internet. With the following command it is available uniquely on the +default. More detailed documentation can be found in the :ref:`RPC index. +` The RPC interface must be enabled for the clients +to communicate with the node but it should not be publicly accessible on the +internet. With the following command, it is available uniquely on the `localhost` address of your machine, on the default port ``8732``. :: @@ -163,7 +163,7 @@ 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 +For example, after starting your node you can check if it has finished synchronizing using:: tezos-client bootstrapped @@ -186,14 +186,14 @@ 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 +aliases (``alice`` in the subsequent commands) 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 smart contracts, which have the form *KT1…*. -We can for example generate a new pair of keys, which can be used locally +We can, for example, generate a new pair of keys, which can be used locally with the alias *bob*:: $ tezos-client gen keys bob @@ -206,7 +206,7 @@ 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 +requires 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. @@ -222,7 +222,7 @@ For more advanced key management we offer :ref:`ledger support Get Free Tez ~~~~~~~~~~~~ -In order to test the networks and help users get familiar with the +To test the networks and help users get familiar with the system, on Zeronet and Carthagenet test networks you can obtain free tez from a `faucet `__. @@ -252,7 +252,7 @@ Please drink carefully and don't abuse the faucet: it only contains Transfers and Receipts ~~~~~~~~~~~~~~~~~~~~~~ -In order to fund our newly created account we need to transfer some +To fund our newly created account, we need to transfer some tez using the `transfer` operation. Every operation returns a `receipt` that recapitulates all the effects of the operation on the blockchain. @@ -318,11 +318,11 @@ produced, here's an excerpt:: The client does a bit of magic to simplify our life and here we see that many details were automatically set for us. Surprisingly, our transfer operation resulted in `two` operations, -first a `revelation` and then a transfer. +first a `revelation`, and then a transfer. Alice's address, obtained from the faucet, is already present on the blockchain, but only in the form of a `public key hash` ``tz1Rj...5w``. -In order to sign operations Alice needs to first reveal the `public +To sign operations, Alice needs to first reveal the `public key` ``edpkuk...3X`` behind the hash, so that other users can verify her signatures. The client is kind enough to prepend a reveal operation before the @@ -331,17 +331,17 @@ transfers will consist of a single operation as expected. Another interesting thing we learn from the receipt is that there are more costs being added on top of the transfer and the burn: `fees`. -In order to encourage a baker to include our operation, and in general +To encourage a baker to include our operation, and in general to pay for the cost of running the blockchain, each operation usually includes a fee that goes to the baker. Fees are variable over time and depend on many factors but the tezos client selects a default for us. -The last important bit of our receipt are the balance updates which -resume which address is being debited or credit of a certain amount. +The last important bit of our receipt is the balance updates that +resume which address is being debited or credited of a certain amount. We see in this case that baker ``tz1Ke...yU`` is being credited one fee for each operation, that Bob's address ``tz1Rk...Ph`` gets 1 tez -and that Alice pays the two fees, the transfer and the burn. +and that Alice pays the two fees, the transfer, and the burn. Now that we have a clear picture of what we are going to pay we can execute the transfer for real, without the dry-run option. @@ -352,8 +352,8 @@ network. Once it receives a block with the operation inside it will return the receipt. -It is advisable to wait several blocks to consider the transaction as -final, for an important operation we advice to wait 60 blocks. +It is advisable to wait for several blocks to consider the transaction as +final, for an important operation we advise to wait for 60 blocks. In the rare case when an operation is lost, how can we be sure that it will not be included in any future block and re-emit it? @@ -371,17 +371,18 @@ Implicit Accounts and Smart Contracts In Tezos there are two kinds of accounts: *implicit accounts* and *smart contracts*. -- The implicit accounts are the *tz1*, *tz2*, and *tz3* we have used - up to now. They are created with a transfer operation to the - account public key hash. +- The implicit accounts are the addresses starting with *tz1*, *tz2*, + and *tz3* we have used up to now. They are created with a transfer + operation to the account public key hash. -- Smart contracts have addresses *KT1* and are created with an - origination operation. They don't have a corresponding secret key - and they run Michelson code each time they receive a transaction. +- Smart contracts have addresses starting with *KT1* and are created + with an origination operation. They don't have a corresponding + secret key and they run Michelson code each time they receive a + transaction. Let's originate our first contract and call it *id*:: - tezos-client originate contract id for alice transferring 1 from alice \ + tezos-client originate contract id transferring 1 from alice \ running ./tests_python/contracts/attic/id.tz \ --init '"hello"' --burn-cap 0.4 @@ -407,7 +408,7 @@ For the sake of this example, here is the `id.tz` contract: code {CAR; NIL operation; PAIR}; It specifies the types for the parameter and storage, and implements a -function which updates the storage with the value passed as parameter +function which updates the storage with the value passed as a parameter and returns the storage unchanged together with an empty list of operations. @@ -443,7 +444,7 @@ 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. +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. @@ -458,30 +459,29 @@ limit for both. The transaction fails if any of the two limits are passed. --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 +storage limits because it takes fewer 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. In this case, you may have to specify some -fees as the baker is expecting some for the resources +fees as the baker is expecting some for the resource usage. Otherwise, you can force a low fee operation using the `--force-low-fee`, with the risk that no baker will include it. More test contracts can be found in directory :src:`tests_python/contracts/`. -An advanced documentation of the smart contract language is available +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 +The node allows validating 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 +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. +have an effect on the context. To avoid this case the client first asks the node to validate the transaction and then sends it. @@ -491,11 +491,11 @@ 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. +tracks the amount of gas and storage that has been consumed. Then the client sends the transaction with the right limits for gas -and storage based on that indicated by the node. +and storage based on those indicated by the node. This is why we were able to submit transactions without specifying -this limits, they were computed for us. +these limits: they were computed for us. More information on validation can be found :ref:`here. ` diff --git a/docs/user/multinetwork.rst b/docs/user/multinetwork.rst index cfd95f6637d6780ec89829d4f52440b115caa392..4eb67f9647570217df859bfe744f89d703e674e6 100644 --- a/docs/user/multinetwork.rst +++ b/docs/user/multinetwork.rst @@ -112,9 +112,9 @@ user-activated upgrades (see `Alias Versus Explicit Configuration`_). the same network name). - ``old_chain_name`` is usually the same as ``chain_name``, except for networks - which were renamed. + that were renamed. -- ``incompatible_chain_name`` is a name which must be different than ``chain_name`` +- ``incompatible_chain_name`` is a name which must be different from ``chain_name`` and ``old_chain_name``. It is thus ensured to be incompatible. It is used for testing purposes. diff --git a/docs/whitedoc/p2p.rst b/docs/whitedoc/p2p.rst index f9d7d859afabf4dbfe34b9bfca5357ec86eb2d7c..70c030fc4ac3138a94cf3551e25ae8d5678db9f9 100644 --- a/docs/whitedoc/p2p.rst +++ b/docs/whitedoc/p2p.rst @@ -7,17 +7,17 @@ This document explains the inner workings of the peer-to-peer layer of the Tezos shell. This part is in charge of establishing and maintaining network connections with other nodes (gossip). -The P2P layer is instantiated by the node. It is parametrized by the +The P2P layer is instantiated by the node. It is parameterized by the type of messages that are exchanged over the network (to allow different P2P protocol versions/extensions), and the type of metadata -associated to each peer. The latter is useful to compute a score for +associated with each peer. The latter is useful to compute a score for each peer that reflects the level of trust we have in it. Different policies can be used when communicating with peers with different score values. The P2P layer is comprised of a pool of connections, a set of operations on those connections, and a set of workers following the -worker pattern pervasively used in the code base. +worker pattern pervasively used in the codebase. The P2P layer is packaged in :package:`tezos-p2p`, which has documentation for all modules. @@ -28,7 +28,7 @@ General operation I/O Scheduling ~~~~~~~~~~~~~~ -The P2P layer uses a scheduling mechanism in order to control its +The P2P layer uses a scheduling mechanism to control its bandwidth usage as well as implementing different policies (e.g. read/write quotas) to different peers. For now, each peer is granted a fair share of the global allocated bandwidth, but it is @@ -54,7 +54,7 @@ possible with a peer; when a queue is full, it is not possible to read `P2p_socket.connection <../api/odoc/tezos-p2p/Tezos_p2p/P2p_socket/index.html#type-connection>`__ type by the P2P layer is basically a UNIX socket upgraded with I/O -scheduling, peer metadata, cryptographic keys and two messages queues +scheduling, peer metadata, cryptographic keys, and two messages queues operated by dedicated workers which operate on those queues. Pool of connections @@ -65,7 +65,7 @@ All the above modules are used in `P2p_pool constitutes the core of the P2P layer, together with the worker processes described below. It comprises various tables of connections as well as methods to query them, also connections are extended with -another message queue where lower level messages (like responses to +another message queue where lower-level messages (like responses to ping) are filtered out and only application-level messages are kept. The main entry point of the P2P layer is in module `P2p @@ -100,7 +100,7 @@ Maintenance worker ------------------ The maintenance worker is in charge of establishing an appropriate -number of connections with other nodes in order to guarantee a +number of connections with other nodes to guarantee a realistic view of the state of the blockchain. It is created with a set of targets to reach regarding the desired amount of peers it needs to keep an active connection to. @@ -115,7 +115,7 @@ Given these bounds, the maintenance worker: * Will be triggered every two minutes, when asked by the shell, or when the minimum or maximum number of acceptable connections is - reached, whichever happens first. + reached, whichever of these three cases happens first. * Will perform the following actions when triggered: if the number of connections is above ``max_threshold``, it will kill connections diff --git a/docs/whitedoc/proof_of_stake.rst b/docs/whitedoc/proof_of_stake.rst index 61128f04aa0e89111688940efe0a089ceee6f4c4..fdca6981141547f552e6796d1ef6d62a8eb0681a 100644 --- a/docs/whitedoc/proof_of_stake.rst +++ b/docs/whitedoc/proof_of_stake.rst @@ -26,15 +26,15 @@ contributes in agreeing on a block by **endorsing** that block. **Baking rights** and **endorsing rights** are determined at the beginning of a **cycle** (a chunk of blocks) by a follow-the-satoshi strategy starting from a **random seed** computed from information -already found on blockchain. +already found on the blockchain. To incentivize participation in the consensus algorithm, delegates are **rewarded** for their baking and endorsing. As a counter-measure against double-baking or double-endorsement a **security deposit** is frozen from the delegate's account. The deposit is either released -after a number of cycles or burnt in case of proven bad behaviour. +after a number of cycles or burnt in case of proven bad behavior. -The remainder of this document contains the detailed description of +The remainder of this document contains a detailed description of the notions which are in bold in the text above. Further External Resources @@ -61,8 +61,8 @@ Blocks ------ The Tezos blockchain is a linked list of blocks. Blocks contain a -header, and a list of operations. The header itself decomposes into a -shell header (common to all protocols) and a protocol specific header. +header and a list of operations. The header itself decomposes into a +shell header (common to all protocols) and a protocol-specific header. Shell header ~~~~~~~~~~~~ @@ -101,7 +101,7 @@ Protocol header Block size ~~~~~~~~~~ -Tezos does not download blocks all at once, but rather considers +Tezos does not download blocks all at once but rather considers headers and various types of operations separately. Transactions are limited by a total maximum size of 512kB (that is 5MB every 10 minutes at most). @@ -115,7 +115,7 @@ transactions for block space. Fitness ~~~~~~~ -To each block we associate a measure of `fitness` which determines the +To each block, we associate a measure of `fitness` which determines the quality of the chain leading to that block. This measure is simply the length of the chain (as in Bitcoin). More precisely, the fitness of a block is 1 plus the fitness of the previous block. The shell changes @@ -152,7 +152,7 @@ Tokens are controlled through a private key called the *manager key*. Tezos accounts let the manager specify a public delegate key. This key may be controlled by the managers themselves, or by another party. The responsibility of the delegate is to take part in -the proof-of-stake consensus algorithm and in the governance of Tezos. +the proof-of-stake consensus algorithm and the governance of Tezos. The manager can generally change the delegate at any time, though contracts can be marked to specify an immutable delegate. Though @@ -187,23 +187,23 @@ gives the majority chain a "headstart". Rolls ~~~~~ -In theory, it would be possible to give each token a serial number, +In theory, it would be possible to give each token a serial number and track the specific tokens assigned to specific delegates. However, -it would be too demanding of nodes to track assignment at such a -granular level. Instead we introduce the concept of rolls. A *roll* +it would be too demanding of nodes to track assignments at such a +granular level. Instead, we introduce the concept of rolls. A *roll* represents a set of coins delegated to a given key. A roll holds ``TOKENS_PER_ROLL`` = 8,000 tokens. When tokens are moved, or a delegate for a contract is changed, the rolls change delegate according to the following algorithm. -Each delegate has a stack of roll ids plus some "change" which is always +Each delegate has a stack of roll identifiers plus some "change" which is always an amount smaller than ``TOKENS_PER_ROLL``. When tokens are moved from one delegate to the other, first, the change is used. If it is not enough, rolls need to be "broken" which means that they move from the delegate stack to a global, unallocated, roll stack. This is done until the amount is covered, and some change possibly remains. -Then, the other delegate is credited. First the amount is added to the +Then, the other delegate is credited. First, the amount is added to the "change". If it becomes greater than ``TOKENS_PER_ROLL``, then rolls are unstacked from the global unallocated roll stack onto the delegate stack. If the global stack is empty, a fresh roll is created. @@ -222,7 +222,7 @@ Roll snapshots Roll snapshots represent the state of rolls for a given block. Roll snapshots are taken every ``BLOCKS_PER_ROLL_SNAPSHOT`` = 256 blocks, -that is 16 times per cycle. There is a tradeoff between memory +which is 16 times per cycle. There is a tradeoff between memory consumption and economic efficiency. If roll snapshots are too frequent, they will consume a lot of memory. If they are too rare, strategic participants could purchase many tokens in anticipation of a snapshot @@ -242,7 +242,7 @@ seed for each cycle. From this random seed, we can seed a cryptographically secure pseudo-random number generator which is used to draw baking rights for a cycle. -To each level is associated a priority list of delegates. +Each level is associated with a priority list of delegates. This list is obtained by randomly selecting an active roll for each position in the list, and then taking the owner of the selected roll. As the draw is independent for each list position, it is possible that @@ -265,12 +265,12 @@ To each level, we associate a list of ``ENDORSERS_PER_BLOCK`` = 32 *endorsers*. Endorsers are drawn similarly as bakers, by randomly selecting 32 active rolls with replacement. -Each endorser verifies the last block that was baked, say at level +Each endorser verifies the last block that was baked, say at the level ``n``, and emits an endorsement operation. The endorsement operations are then baked in block ``n+1``. Once block ``n+1`` is baked, no other endorsement for block ``n`` will be considered valid. -It is possible that an endorser has more than one endorsement +An endorser may have more than one endorsement slot. However, the endorser injects a single endorsement operation, which represents all of its endorsement slots. In what follows, when we say "the number of endorsements a block contains", we do not refer @@ -361,7 +361,7 @@ randomly select a roll snapshot from cycle ``n-2`` and to randomly select rolls in the selected snapshot. The selected rolls determine the baking and endorsing rights in cycle ``n+PRESERVED_CYCLES``. -The random seed for cycle ``n`` is a 256 bit number generated at the +The random seed for cycle ``n`` is a 256-bit number generated at the very end of cycle ``n-1`` from nonces to which delegates commit during cycle ``n-2``. One out of every ``BLOCKS_PER_COMMITMENT`` = 32 blocks can contain a commitment. There are therefore at most @@ -377,7 +377,7 @@ not forfeited. A *nonce revelation* is an operation, and multiple nonce revelations can thus be included in a block. A baker receives a ``SEED_NONCE_REVELATION_TIP`` = 1/8 ꜩ reward for including a -revelation. Revelations are free operations which do not compete with +revelation. Revelations are free operations that do not compete with transactions for block space. Up to ``MAX_REVELATIONS_PER_BLOCK`` = 32 revelations can be contained in any given block. Thus, (``BLOCKS_PER_CYCLE`` / ``MAX_REVELATIONS_PER_BLOCK``) / ``BLOCKS_PER_COMMITMENT`` = 4 diff --git a/docs/whitedoc/validation.rst b/docs/whitedoc/validation.rst index 4fbecb4b8bf97263bd22a1cd5039298f3e609c66..69e7f742c99810f5693185bf61da236c6abf2a47 100644 --- a/docs/whitedoc/validation.rst +++ b/docs/whitedoc/validation.rst @@ -32,14 +32,14 @@ to validate, and active (test)chains. A *chain validator* worker is launched by the validator for each *chain* that it considers alive. Each chain validator is responsible for handling blocks that belong to this chain, and select the best head for -this chain. A main chain validator is spawned for the main chain that +this chain. A chain validator is spawned for the main chain that starts at the genesis, a second one when there is an active test chain. Forking a chain is decided from within the economic protocol. In version Alpha, this is only used to try new protocols before self amending the main chain. The chain validator spawns one *peer validator* worker per connected -peer. This set is updated, grown or shrunk on the fly, according to the +peer. The set of peer validators is updated, grown, or shrunk on the fly, according to the connections and disconnections signals from the peer-to-peer component. Each peer validator will treat new head proposals from the associated peer, one at a time, in a loop. In the simple case, when a peer @@ -51,26 +51,26 @@ more than one block, mostly during the initial bootstrap phase, the peer worker launches a *bootstrap pipeline* task. A third scheme is planned (but not yet implemented) for validating -alternative chains: the *multipass validator*. This method is quite more -complex, its goal is to detect erroneous blocks as soon as possible, -without having to download all the chain data. This will work by first -validating the block headers, then the operations that act on the -fitness, and finally the remaining operations. The mechanism is -actually a bit more flexible, and allows for an arbitrary number of -lists of operations. The shell will only consider forks of a given -length, that is exported by the protocol, so that block headers and -operations are validated in the context of an ancestor block that is -in a close enough time window. In version Alpha, the check performed -on block headers is that the baking slots, baker signatures and -timestamp deltas are right. It can also detect too large fitness gaps, -as the fitness difference between two consecutive blocks is bounded in -Alpha. The operations that act on fitness are endorsements, whose -checks consist in verifying the endorsement slots and endorsers' +alternative chains: the *multipass validator*. This method is quite +more complex, its goal is to detect erroneous blocks as soon as +possible, without having to download all the chain data. This process +will work by first validating the block headers, then the operations +that act on the fitness, and finally the remaining operations. The +mechanism is actually a bit more flexible and allows for an arbitrary +number of lists of operations. The shell will only consider forks of a +given length, that is exported by the protocol, so that block headers +and operations are validated in the context of an ancestor block that +is in a close enough time window. In version Alpha, the check +performed on block headers is that the baking slots, baker signatures, +and timestamp deltas are right. It can also detect too large fitness +gaps, as the fitness difference between two consecutive blocks is +bounded in Alpha. The operations that act on fitness are endorsements, +whose checks consist in verifying the endorsement slots and endorsers' signatures. For that to be sound, the fork limit is set to not allow rewinding before the baking and endorsing slots are set. Each of these three peer validator tasks (head increment, bootstrap -pipeline or multipass) will interact with the distributed DB to get +pipeline, or multipass) will interact with the distributed DB to get the data they need (block headers and operations). When they have everything needed for a block, they will call the *block validator*. @@ -92,21 +92,21 @@ RAM), that is responsible for the transmission of operations for this chain over the peer-to-peer network. To prevent spam, this prevalidator must select the set of operations -that it considers valid, and the ones that it chooses to broadcast. +that it considers valid and the ones that it chooses to broadcast. This is done by constantly baking a dummy block, floating over the current head, and growing as new operations are received. Operations that get included can be broadcast unconditionally. -Operations that are included are classified into categories. Some -(such as bad signatures or garbage byte sequences) are dismissed. They -are put in a temporary bounded set for quick rejection, and the peer -that sent it is kicked. Some other operations are temporarily refused: -they come too soon or too late. For instance, in Alpha, contracts have -counters, and operations with counters in the future are classified as +Operations that are included are classified. Some (such as bad +signatures or garbage byte sequences) are dismissed. They are put in a +temporary bounded set for quick rejection, and the peer that sent it +is kicked. Some other operations are temporarily refused: they come +too soon or too late. For instance, in Alpha, contracts have counters, +and operations with counters in the future are classified as temporarily refused. A malicious peer could easily flood the mempool with such operations, so they are put in a bounded set. Another -bounded set is also kept for a third kind of non inclusion: operations +bounded set is also kept for a third kind of non-inclusion: operations that could be valid in another branch. Distributed DB