Migrate to mdBook

.gitignore

@@ -0,0 +1 @@
+book

README.md

@@ -2,17 +2,19 @@
 
 [![Community](https://img.shields.io/badge/chat%20on-discord-orange?&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.gg/YsnTPcSfWQ)
 
-- [Specs](#specs)
+## Building From Source
 
-## Specs
+To build book:
 
-- [Architecture](specs/architecture.md)
-- [Data Structures](specs/data_structures.md)
-- [Consensus](specs/consensus.md)
-- [Block Proposer](specs/block_proposer.md)
-- [Networking](specs/networking.md)
-- [Light client](specs/light_client.md)
-- [Node types](specs/node_types.md)
+```sh
+mdbook build
+```
+
+To serve locally:
+
+```sh
+mdbook serve
+```
 
 ## Contributing
 

book.toml

@@ -0,0 +1,13 @@
+[book]
+authors = ["LazyLedger Labs"]
+language = "en"
+multilingual = false
+src = "src"
+title = "LazyLedger Specifications"
+
+[output.html]
+mathjax-support = true
+git-repository-url = "https://github.com/lazyledger/lazyledger-specs"
+
+[rust]
+edition = "2018"

src/README.md

@@ -0,0 +1,14 @@
+# LazyLedger Specifications
+
+- [Specification](./specs/README.md)
+  - [Architecture](./specs/architecture.md)
+  - [Data Structures](./specs/data_structures.md)
+  - [Consensus](./specs/consensus.md)
+  - [Block Proposer](./specs/block_proposer.md)
+  - [Networking](./specs/networking.md)
+  - [Light client](./specs/light_client.md)
+  - [Node types](./specs/node_types.md)
+- [Rationale](./rationale/README.md)
+  - [Block Rewards](./rationale/rewards.md)
+  - [Distributing Rewards and Penalties](./rationale/distributing_rewards.md)
+  - [Message Layout](./rationale/message_block_layout.md)

src/SUMMARY.md

@@ -0,0 +1,16 @@
+# Summary
+
+[LazyLedger Specifications](./README.md)
+
+- [Specification](./specs/README.md)
+  - [Architecture](./specs/architecture.md)
+  - [Data Structures](./specs/data_structures.md)
+  - [Consensus](./specs/consensus.md)
+  - [Block Proposer](./specs/block_proposer.md)
+  - [Networking](./specs/networking.md)
+  - [Light client](./specs/light_client.md)
+  - [Node types](./specs/node_types.md)
+- [Rationale](./rationale/README.md)
+  - [Block Rewards](./rationale/rewards.md)
+  - [Distributing Rewards and Penalties](./rationale/distributing_rewards.md)
+  - [Message Layout](./rationale/message_block_layout.md)

src/rationale/README.md

@@ -0,0 +1,5 @@
+# Rationale
+
+- [Block Rewards](./rewards.md)
+- [Distributing Rewards and Penalties](./distributing_rewards.md)
+- [Message Layout](./message_block_layout.md)

rationale/distributing_rewards.md → src/rationale/distributing_rewards.md

@@ -19,26 +19,26 @@ This forms the primary motivation of the scheme discussed here: a mechanism for
 
 The scheme presented here is an incarnation of Cosmos' [F1 fee distribution scheme](https://github.com/cosmos/cosmos-sdk/blob/master/docs/spec/fee_distribution/f1_fee_distr.pdf). F1 has the nice property of being approximation-free and, with proper implementation details, can be highly efficient with state usage and completely iteration-free in all cases.
 
-Naively, when considering a single block, the reward that should be given to a delegator with stake $x$, who is delegating to a validator with total voting power $n$, whose reward in that block is $T$, is:
+Naively, when considering a single block, the reward that should be given to a delegator with stake \\( x \\), who is delegating to a validator with total voting power \\( n \\), whose reward in that block is \\( T \\), is:
 
 $$
 \text{naive reward} = x \frac{T}{n}
 $$
 
 In other words, the voting power contributed by the delegator multiplied by the _reward rate_, i.e. the rewards per unit of voting power. We note that if the total voting power of a validator remains constant forever, then the above equation holds and is approximation-free. However, changes to the total voting power need to be accounted for.
 
-Blocks between two changes to a validator's voting power (i.e. whenever a user delegates or undelegates stake) are a _period_. Every time a validator's voting power changes (i.e. a new period $f$ begins), an entry $Entry_f$ for this period is saved in state, which records_the reward rate up to the beginning of_ $f$. This is simply the sum of the reward rate up to the beginning of previous period $f-1$ and the reward rate of the period $f$ itself:
+Blocks between two changes to a validator's voting power (i.e. whenever a user delegates or undelegates stake) are a _period_. Every time a validator's voting power changes (i.e. a new period \\( f \\) begins), an entry \\( Entry_f \\) for this period is saved in state, which records_the reward rate up to the beginning of_ \\( f \\). This is simply the sum of the reward rate up to the beginning of previous period \\( f-1 \\) and the reward rate of the period \\( f \\) itself:
 
 $$
 Entry_f = \begin{cases}
-    0 & f = 0 \\
-    Entry_{f-1} + \frac{T_f}{n_f} & f > 0 \\
+    0 & f = 0 \\\\
+    Entry_{f-1} + \frac{T_f}{n_f} & f > 0 \\\\
 \end{cases}
 $$
 
-Note that $Entry$ is a monotonically increasing function.
+Note that \\( Entry \\) is a monotonically increasing function.
 
-Finally, the raw reward for a delegation is simply proportional to the difference in entries between the period where undelegation ended ($f$) and where it began ($k$).
+Finally, the raw reward for a delegation is simply proportional to the difference in entries between the period where undelegation ended (\\( f \\)) and where it began (\\( k \\)).
 
 $$
 \text{reward} = x (Entry_f - Entry_k)

rationale/rewards.md → src/rationale/rewards.md

@@ -5,14 +5,15 @@ Block rewards scale with the inverse square root of the total validating stake.
 Note that non-constant reward scaling opens up the system to [gatekeeping attacks](https://arxiv.org/abs/1811.00742), whereby validators are incentivized to prevent new validators from joining the validator set to keep their returns high. This should not be an issue in practice in the same way as [feather forks](https://bitcointalk.org/index.php?topic=312668.0) are not an issue in practice, but is nonetheless a theoretical issue that is noted here.
 
 The formula to calculate the reward per block uses the following symbols:
-| symbol | note                              |
-|--------|-----------------------------------|
-| $R_B$  | Rewards per block, in coins.      |
-| $I_T$  | Target annual issuance, in coins. |
-| $t_B$  | Block time, in seconds.           |
-| $t_Y$  | Seconds per year.                 |
-| $S_0$  | Initial coin supply.              |
-| $S_T$  | Total staked coins.               |
+
+| symbol      | note                              |
+|-------------|-----------------------------------|
+| \\( R_B \\) | Rewards per block, in coins.      |
+| \\( I_T \\) | Target annual issuance, in coins. |
+| \\( t_B \\) | Block time, in seconds.           |
+| \\( t_Y \\) | Seconds per year.                 |
+| \\( S_0 \\) | Initial coin supply.              |
+| \\( S_T \\) | Total staked coins.               |
 
 Note that for the seconds per year we use a fixed `31,536,000`, omitting leap seconds for simplicity.
 
@@ -22,4 +23,4 @@ $$
 R_B(S_T) = I_T \frac{t_B}{t_Y} \frac{\sqrt{S_T}}{\sqrt{S_0}} = \left( \frac{I_T t_B }{t_Y \sqrt{S_0}} \right) \sqrt{S_T}
 $$
 
-If 100% of the initial supply of coins stake, then exactly $I_T$ new coins will be issued per $\frac{t_Y}{t_B}$ blocks. If fewer than 100% of the initial supply of coins stake, then fewer than $I_T$ new coins will be issued, but the decrease will be square-root rather than linear. If greater than 100% of the initial supply of coins stake (e.g. after some time, additional coins will be in circulation due to previous issuance), then greater than $I_T$ new coins will be issued, but again scaling sub-linearly.
+If 100% of the initial supply of coins stake, then exactly \\( I_T \\) new coins will be issued per \\( \frac{t_Y}{t_B} \\) blocks. If fewer than 100% of the initial supply of coins stake, then fewer than \\( I_T \\) new coins will be issued, but the decrease will be square-root rather than linear. If greater than 100% of the initial supply of coins stake (e.g. after some time, additional coins will be in circulation due to previous issuance), then greater than \\( I_T \\) new coins will be issued, but again scaling sub-linearly.

src/specs/README.md

@@ -0,0 +1,9 @@
+# Specification
+
+- [Architecture](./architecture.md)
+- [Data Structures](./data_structures.md)
+- [Consensus](./consensus.md)
+- [Block Proposer](./block_proposer.md)
+- [Networking](./networking.md)
+- [Light client](./light_client.md)
+- [Node types](./node_types.md)

specs/networking.md → src/specs/networking.md

@@ -22,7 +22,11 @@
 
 ### ConsensusProposal
 
-Defined as `ConsensusProposal` [here](./proto/consensus.proto).
+Defined as `ConsensusProposal`:
+
+```protobuf
+{{#include ./proto/consensus.proto:ConsensusProposal}}
+```
 
 When receiving a new block proposal `proposal` from the network, the following steps are performed in order. _Must_ indicates that peers must be blacklisted (to prevent DoS attacks) and _should_ indicates that the network message can simply be ignored.
 
@@ -51,7 +55,11 @@ When receiving a new block proposal `proposal` from the network, the following s
 
 ### WireTxPayForMessage
 
-Defined as `WireTxPayForMessage` as a [wire type](./proto/wire.proto).
+Defined as `WireTxPayForMessage`:
+
+```protobuf
+{{#include ./proto/wire.proto:WireTxPayForMessage}}
+```
 
 Accepting a `WireTxPayForMessage` into the mempool requires different logic than other transactions in LazyLedger, since it leverages the paradigm of block proposers being able to malleate transaction data. Unlike [SignedTransactionDataPayForMessage](./data_structures.md#signedtransactiondatapayformessage) (the canonical data type that is included in blocks and committed to with a data root in the block header), each `WireTxPayForMessage` (the over-the-wire representation of the same) has potentially multiple signatures.
 

specs/proto/consensus.proto → src/specs/proto/consensus.proto

@@ -18,6 +18,7 @@ enum SignedMsgType {
   SignedMsgTypeProposal = 32;
 }
 
+// ANCHOR: ConsensusProposal
 message ConsensusProposal {
   SignedMsgType type = 1;
   int32 round = 2;
@@ -29,6 +30,7 @@ message ConsensusProposal {
   // 64-byte signature
   bytes proposer_signature = 6;
 }
+// ANCHOR_END: ConsensusProposal
 
 message ConsensusVote {
   SignedMsgType type = 1;

specs/proto/wire.proto → src/specs/proto/wire.proto

@@ -31,6 +31,7 @@ message WireTxTransfer {
   uint64 nonce = 4;
 }
 
+// ANCHOR: WireTxPayForMessage
 message WireTxPayForMessage {
   TransactionFee fee = 1;
   uint64 nonce = 2;
@@ -40,6 +41,7 @@ message WireTxPayForMessage {
   bytes message = 5;
   repeated MessageCommitmentAndSignature message_commitment_and_signature = 6;
 }
+// ANCHOR_END: WireTxPayForMessage
 
 message WireTxCreateValidator {
   TransactionFee fee = 1;