-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
- Loading branch information
Showing
21 changed files
with
1,227 additions
and
7 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Binary file removed
BIN
-32.9 KB
developer_docs/sequence_diagrams/new-block-received-from-peer-peer-not-originator.pdf
Binary file not shown.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
book |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
[book] | ||
authors = ["Alan Szepieniec"] | ||
language = "en" | ||
multilingual = false | ||
src = "src" | ||
title = "Neptune Documentation" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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>. |
Oops, something went wrong.