Merge pull request #160 from Neptune-Crypto/asz/consensus-logic-docum…

…entation

Add MdBook for Documentation

- Add mdBook for documentation
- Migrate existing documentations there
- Add documentation for consensus logic wrt transactions

README.md

@@ -42,6 +42,14 @@ With a functioning version of cargo, compilation on Windows should just work out
 
 If you don't have a static IPv4, then try connecting to other nodes with IPv6. It's our experience that you will then be able to open and receive connections to other nodes through Nepture Core's built-in peer-discovery process.
 
+## Documentation
+
+Documentation uses [https://rust-lang.github.io/mdBook/](mdBook). To run a local copy:
+
+ - install mdBook: `cargo install mdbook`
+ - enter into the `docs/` directory: `cd docs`
+ - run server: `mdbook serve --open`
+
 ## Dashboard
 
 This software comes with a dashboard that communicates with the daemon. The dashboard is a console-based user interface to generate addresses, receive and send money, and monitor the behavior of the client. The daemon must be running before the dashboard is started. To start the dashboard, run: `neptune-dashboard`. (If you set daemon's RPC port to a custom value specify that value with the flag `--port [port]`.)

docs/.gitignore

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

docs/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Alan Szepieniec"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Neptune Documentation"

docs/src/SUMMARY.md

@@ -0,0 +1,14 @@
+# Summary
+
+- [Consensus](./consensus.md)
+  - [Transaction](./consensus/transaction.md)
+  - [Block](./consensus/block.md)
+- [Neptune-Core](./neptune-core.md)
+  - [Overview](./neptune-core/overview.md)
+  - [Events](./neptune-core/events.md)
+  - [Syncing](./neptune-core/syncing.md)
+  - [Sequences](./neptune-core/sequences.md)
+  - [Reorganization](./neptune-core/reorganization.md)
+- [Contributing](./contributing.md)
+  - [Git Workflow](./contributing/git-workflow.md)
+  - [Git Message](./contributing/git-message.md)

docs/src/consensus.md

@@ -0,0 +1,12 @@
+# Consensus
+
+Neptune achieves succinctness by requiring STARK proofs to certify most of the consensus-critical logic. As a consequence, verifying and even running a full node is cheap. The tradeoff is that someone has to produce these STARK proofs, and this burden ultimately falls on the miner.
+
+The particular proof system that Neptune uses is [Triton VM](https://triton-vm.org/). The particular computations that are proven (and verified) as part of consensus logic are documented here.
+
+Consensus is the feature of a network whose nodes overwhelmingly agree on the current contents of a database, typically a blockchain. This database is append-only. While reorganizations can happen they are expected to be rare and shallow. Every once in a while, a new block is added. The block contains, among other things, a transaction. [Block](./consensus/block.md)s and [Transaction](./consensus/transaction.md)s are the key data objects that consensus pertains to. The *consensus logic* determines which blocks and transactions are *valid* and *confirmable*.
+
+Note that there is a distinction between *valid* and *confirmable*. Validity refers to the internal consistency of a data object. Confirmable refers to its current relation to the rest of the blockchain. For example, having insufficient proof-of-work or including a double-spending transaction makes a block invalid. But a block can be both valid and unconfirmable, for instance if its timestamp is too far into the future. STARK proofs are capable of establishing validity but not confirmability.
+
+Since both blocks and transactions come with STARK proofs certifying their validity, it is worthwhile to separate the kernel from the proof. The *kernel* is the actual payload data that appears on the blockchain, and the object that the proof asserts validity of. There can be different proofs certifying the validity of a block or transaction kernel. Proofs can typically be recursed away so that the marginal cost of storing them is zero.
+

docs/src/consensus/block.md

@@ -0,0 +1,71 @@
+# Block
+
+A block kernel consists of a header and a body. The block header has constant size and consists of:
+ - `version` the version of the Neptune protocol
+ - `height` the block height represented as a `BFieldElement`
+ - `prev_block_digest` the hash of the block's predecessor
+ - `timestamp` when the block was found
+ - `nonce` randomness for proof-of-work
+ - `max_block_size` maximum block size in bytes
+ - `proof_of_work_line` approximate number of hashes computed in the block's direct lineage
+ - `proof_of_work_family` approximate number of hashes computed in the block's family, including uncles
+ - `difficulty` approximate number of hashes required to find a block.
+ - (Other fields may be added to account for automatically updating network parameters.)
+
+The block body holds the variable-size data, consisting of:
+ - `transaction` every block contains one transaction, which represents the merger of all broadcasted transactions that the miner decided to confirm.
+ - `mutator_set_accumulator` the <span style="color:red">mutator set</span> is the data structure that holds the UTXOs. It is simultaneously an accumulator (giving rise to a compact representation and compact membership proofs) and an anonymity architecture (so that outputs from one transactions cannot be linked to inputs to another).
+ - `lock_free_mmr_accumulator` the data structure holding lock-free UTXOs
+ - `block_mmr_accumulator` the peaks of a Merkle mountain range that contains all historical blocks in the current block's line.
+ - `uncle_blocks` the digests of uncle blocks not listed so far. The miner needs to prove that between the latest common ancestor between the current block and all listed uncles, none of the listed uncles were included before.
+
+## Validity
+
+A block is *valid* if (any of):
+ - ***a)*** it is the genesis block
+ - ***b)*** the incremental validity conditions are satisfied
+ - ***c)*** it lives in the `block_mmr_accumulator` of a block that is valid.
+
+### A: Genesis Block
+
+The genesis block is hardcoded in the source code, see `genesis_block` in `block/mod.rs`.
+
+### B: Incremental Validity
+
+A block is incrementally valid if (all of):
+ - ***a)*** the transaction is valid
+ - ***b)*** the transaction's coinbase conforms with the block subsidy schedule
+ - ***c)*** all the inputs in the transaction either live in the lock-free UTXO MMR or have at least one index that is absent from the mutator set SWBF
+ - ***d)*** the `mutator_set_accumulator` results from applying all removal records and then all addition records to the previous block's `mutator_set_accumulator`
+ - ***e)*** the `block_mmr_accumulator` results from appending the previous block's hash to the previous block's `block_mmr_accumulator`
+ - ***f)*** there is an ancestor block `luca` of the current block such that for each uncle block `uncle`
+   - `uncle` is valid
+   - `luca` is an ancestor of `uncle`
+   - neither `luca` nor any of the blocks between `luca` and the current block list `uncle` as an uncle block
+ - ***g)*** the `version` matches that of its predecessor or is member of a predefined list of exceptions
+ - ***h)*** the `height` is one greater than that of its predecessor
+ - ***i)*** the `timestamp` is greater than that of its predecssor
+ - ***j)*** the network statistics trackers are updated correctly
+ - ***k)*** the variable network parameters are updated correctly.
+
+### C: Mmr Membership
+
+A block is valid if it lives in the `block_mmr_accumulator` of a valid block. This feature ensures several things.
+ 1. It is possible to prove that one block is an ancestor of another.
+ 2. Archival nodes do not need to store old block proofs; storing the most recent block proof suffices.
+ 3. Non-tip blocks can be quickly verified to be valid and, if the receiver is synchronized to the tip, canonical as well.
+ 4. In case of reorganization, storing the now-abandoned tip proof continues to suffice to establish the *validity* of shared blocks. (That said, an archival node should prove *canonicity* of shared blocks also, and to do this he must synchronize and download all blocks on the new fork.)
+
+## Confirmability
+
+A block is *confirmable* if (all of):
+ - ***a)*** it is valid
+ - ***b)*** its timestamp is less than 10 minutes into the future
+ - ***c)*** its size is less than the `max_block_size` stipulated by the previous block
+ - ***d)*** its hash is less than the previous block's `target_difficulty`.
+
+Confirmability is not something that can be proven. It must be checked explicitly by the node upon receiving the block.
+
+## Canonicity
+
+A block is *canonical* if it lives on the <span style="color:red">longest chain</span>.