Merge pull request #463 from trilitech/Nic-review-baking

update Baking with the possibility of staking

docs/architecture/bakers.md

@@ -6,12 +6,11 @@ last_update:
 ---
 
 Baking is the process of creating new blocks in the Tezos blockchain.
-Bakers are programs complementary to Tezos nodes that cooperate to achieve consensus about the next block to add.
+Bakers are executables running alongside Tezos nodes that cooperate to achieve consensus about the next block to add.
 Bakers validate pending operations, package them into a block, sign the block, propose the new block to other nodes, and verify that the blocks that other bakers propose are valid.
 
-Bakers are run on behalf of user accounts which stake tez to guarantee honest participation and receive rewards for their participation.
-The baker has access to the account's private key, which it uses to sign blocks and operations.
-By extension, bakers also denote the users running baker on behalf of their user accounts.
+Baker executables are run on behalf of user accounts.
+By extension, bakers also denote the users running baker daemons on behalf of their user accounts.
 
 ## The baking process
 
@@ -20,33 +19,79 @@ The baking process includes many steps that Tezos users and developers don't nee
 1. The protocol selects in advance a list of bakers for each block to create in a _cycle_, which is a certain number of blocks.
 1. It also selects a list of bakers to act as validators.
 These bakers are responsible for validating the blocks that other bakers create and publishing _attestations_ that the block is valid.
-1. The first baker on the list has a certain amount of time to create the next block.
-It packages pending operations into a block, signs it, and distributes it to the validators and other nodes.
-1. If the first baker doesn't publish a block in time, the next baker on the list has a certain amount of time to bake a block, and so on until a block is created.
+1. The first baker on the list has a certain amount of time (called a round) to create the next block.
+It packages pending operations into a block, signs it, and distributes it to other nodes.
+1. If the first baker doesn't publish a block in time, the next baker on the list has a certain amount of time to bake a block (a new round), and so on until a block is created.
 1. The validators verify the block and publish their attestations in future blocks.
 1. The next list of bakers create the next block, until the end of the cycle.
 
+Note that:
+- The presentation above is somewhat simplified; in reality, validation is done in two phases, called pre-attestation and attestation.
+- For any given block and round, only one baker has the right to create the block, and several bakers have the right to (pre-)attest the block.
+
 ## Becoming a baker
 
-To become a baker, you must create an account to act as a _delegate_, which is an account that is authorized to bake blocks and attest blocks that other accounts bake.
+To become a baker, you must create an account to act as a _delegate_, which is an account that is authorized to bake blocks and attest blocks that other accounts bake, and also to receive delegations (and stake) from other accounts, as explained later.
 Delegates temporarily stake tez as a security deposit to ensure that they are acting according to the rules of the protocol.
-This stake stays locked for a certain number of cycles before the delegate can begin baking.
-Similarly, when bakers stop baking, their stake is unlocked after a certain number of cycles.
+Deposits can be "unstaked" later, either partially (at any time) or totally (when bakers stop baking).
+There is a delay of a certain number of cycles from the moment when the tez are staked until the delegate can begin baking.
+Similarly, when tez are unstaked, they are unlocked after a certain number of cycles.
+Staked tez may be slashed by the protocol if the baker misbehaves (e.g., proposes or attests two different blocks for the same level).
+
+A delegate participates in consensus in proportion to their _baking power_: the more baking power a delegate has, the more likely it is to be selected to bake or to validate blocks and thus receive the rewards.
+The baking power of a delegate is computed from the amounts of tez staked (by its own and by all its stakers) and owned (by its own and by all its delegators), knowing that non-staked tez are weighted half as much as staked tez in the sum.
 
-The delegate must stake at least least 6,000 tez, either from its own account or from tez that delegators delegate to it.
-The more tez a delegate has, both from its own account and from delegators, the more likely it is to be selected to bake a block and thus receive the rewards.
+The delegate must have a baking power of at least 6,000 tez to be allowed to bake.
 
-Bakers must run at least one Tezos node and a baker program to go with it.
-These baker programs must run at all times with a stable internet connection, because inactive bakers are automatically removed from the network.
+A delegate also participates in [governance](/architecture/governance) in proportion to their _voting power_.
+The voting power of a delegate is computed in a similar way to the baking power except that no distinction is made between tez that are staked or not staked.
+
+Bakers must run at least one Tezos node and a baker service to go with it.
+These services must run at all times with a stable power source and internet connection, because periods of inactivity for a baker entail losses of rewards, and eventually being marked as inactive and temporarily excluded from baking.
 
 ## Delegating to a baker
 
-If you don't have enough tez to become a baker or don't want to run a baking node, you can delegate tez to a baker, which makes you a _delegator_.
-The delegate doesn't have control over your tez and you can spend your tez at any time or withdraw your delegation, but the tez that you delegate counts toward the amount of tez that the delegate has for baking purposes.
-Delegators receive a share of the delegate's rewards in proportion to the amount of tez that they delegate.
+If you don't have enough tez to become a baker or don't want to run a baking node, you can choose a baker as your delegate, which makes you a _delegator_.
+The delegate doesn't have control over your tez and you can spend your tez at any time or withdraw your delegation, but half of the tez that you delegate counts toward the baking power of the delegate. Also, delegated tez increase the voting power of your baker: a delegate's voting power is the sum of its own tez plus the tez delegated to it.
+
+In exchange, delegates may share some part of their rewards with you, in proportion to the amount of available tez in your account (technically, the minimal balance during each cycle).
+Check your delegate's conditions for distributing rewards.
+
+Delegating incurs no risk for the delegator: the delegate has no control over the tez and the delegator is not punished if the delegate misbehaves.
+
+## Staking with a baker
+
+If you want to get a bigger share of your delegate's rewards, you can temporarily stake any amount of tez from your account with your baker, provided your baker accepts staking.
+All the tez you stake don't leave your account: they are frozen in your account,
+but contribute to the baker's security deposit, and are locked under the same conditions as the baker's own staked tez. Hence, they are slashed if the baker misbehaves.
+In exchange of agreeing to temporarily lock these tez and sharing the risks with your delegate, you get a bigger share of the delegate's rewards.
+Staking rewards accrue automatically, and are allocated by the protocol: stakers earn rewards whenever their bakers do, and don't have to wait for the baker to distribute them (unlike delegation rewards).
+
+Later on, you may choose to unstake part or all of the staked tez, that will be unlocked after a certain delay.
+
+To stake tez, you start by delegating to a baker's account (which should accepts staking and not be "overstaked"), then you stake a certain amount of your tez to the baker.
+Thus, you can earn staking rewards on some frozen tez while leaving some delegated tez liquid for immediate use.
+
+Since you may have only one delegate, you can only stake with one baker at a time.
+
+## Summary
+
+In summary, here is a comparison betwen the staking and delegating options above:
+
+  | Staking | Delegating
+--- | --- | ---
+Increase baking power | 100% | 50%
+Increase voting power | 100% | 100%
+Reward delay | None | 2 cycles (about 6 days)
+Reward route | Direct to staker | To baker who manually sends to delegator
+Funds availability | Frozen (locked) | Liquid (unlocked)
+Unlock delay | 4 cycles (about 10 days) | None
+Slashing exposure | Yes | No
 
 ## References
 
-For more information about the different options to participate to the Tezos network (baking, staking, or delegating), see [Running Octez](https://tezos.gitlab.io/introduction/howtorun.htm) in the Octez documentation.
+To start delegating and staking, use the app at https://stake.tezos.com.
+
+For more information about the different options to participate to the Tezos network (baking, staking, or delegating), see [Running Octez](https://tezos.gitlab.io/introduction/howtorun.html) in the Octez documentation.
 
 For full details about baking, see [Node and Baking](https://opentezos.com/node-baking/baking/introduction/) on opentezos.com.

docs/overview/tezos-different.md

@@ -16,19 +16,12 @@ Anyone who holds XTZ — the chain's native token — can propose changes to how
 
 ## Tezos uses proof of stake
 
-The proof-of-stake consensus model eliminates the need for high energy use, making it the "green" choice for blockchains. Instead of competing to achieve consensus as in proof-of-work models, Tezos nodes (called *bakers*) stake Tezos tokens to earn the right to create blocks and receive rewards. Tezos's approach to consensus has been described as [Liquid Proof of Stake](https://medium.com/tezos/liquid-proof-of-stake-aec2f7ef1da7).
+The proof-of-stake consensus mechanism eliminates the need for high energy use, making it the "green" choice for blockchains. Instead of competing to achieve consensus as in proof-of-work mechanisms, Tezos nodes (called *bakers*) stake Tezos tokens to earn the right to create blocks and receive rewards. Users who want to participate without running a node themselves can delegate and stake tokens to a baker for a share of the rewards. Bakers and stakers keep control of their tokens in that they can unstake them later; and delegators keep complete control of their tokens.
 
-Users who want to participate without running a node themselves can delegate and stake tokens to a baker for a share of the baker's rewards. Users retain full control of their delegated and staked tokens; delegated tokens remain liquid and staked tokens are frozen for a short time but remain in the user's account and can be made liquid after a short delay.
-<!-- TODO link to more detailed info about delegating and staking from the non-baker perspective -->
-
-The proof-of-stake model improves scalability and encourages cooperation via incentives. It also increases the cost of 51% attacks and avoids environmentally wasteful proof-of-work. Tezos launched in June 2018 as one of the first major proof-of-stake networks.
+Tezos' proof-of-stake mechanism improves scalability and encourages cooperation via incentives. It also increases the cost of consensus attacks and avoids environmentally wasteful proof-of-work. Tezos launched in June 2018 as one of the first major proof-of-stake networks.
 
 For more information about how Tezos handles proof of stake, see https://tezos.gitlab.io/alpha/proof_of_stake.html.
 
-## Tezos accepts multiple languages
-
-Tezos provides a few different languages for developers to choose from, according to their use case, including versions of Python and JavaScript/TypeScript. For more information, see [Languages](/smart-contracts/languages/).
-
 ## Tezos has a robust layer 2 ecosystem
 
 Tezos provides tools that allow high scalability on a layer above the primary Tezos blockchain, known as layer 2. [Smart Rollups](/architecture/smart-rollups) can run large amounts of logic and handle large amounts of data in a separate environment without slowing Tezos itself down. The [Data Availability Layer](/architecture/data-availability-layer) provides high-throughput data to Smart Rollups.