spec: migrate spec at v0.7.1. into main (#9098)

tendermint · Jul 26, 2022 · a7049ed · a7049ed
2 parents a11b774 + 0323bd5
commit a7049ed
Show file tree

Hide file tree

Showing 164 changed files with 39,721 additions and 7 deletions.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -7,4 +7,6 @@
 # global owners are only requested if there isn't a more specific
 # codeowner specified below. For this reason, the global codeowners
 # are often repeated in package-level definitions.
-*      @ebuchman @cmwaters @tychoish @williambanfield @creachadair
+*      @ebuchman @cmwaters @tychoish @williambanfield @creachadair @thanethomson @sergio-mena @jmalicevic
+
+/spec @cason @sergio-mena @jmalicevic @milosevic
diff --git a/.github/ISSUE_TEMPLATE/proposal.md b/.github/ISSUE_TEMPLATE/proposal.md
@@ -0,0 +1,37 @@
+---
+name: Protocol Change Proposal
+about: Create a proposal to request a change to the protocol
+
+---
+
+<!-- < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < ☺ 
+v                            ✰  Thanks for opening an issue! ✰    
+v    Before smashing the submit button please review the template.
+v    Word of caution: Under-specified proposals may be rejected summarily 
+☺ > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >  -->
+
+# Protocol Change Proposal
+
+## Summary
+
+<!-- Short, concise description of the proposed change -->
+
+## Problem Definition
+
+<!-- Why do we need this change? 
+What problems may be addressed by introducing this change?
+What benefits does Tendermint stand to gain by including this change?
+Are there any disadvantages of including this change? -->
+
+## Proposal
+
+<!-- Detailed description of requirements of implementation -->
+
+____
+
+#### For Admin Use
+
+- [ ] Not duplicate issue
+- [ ] Appropriate labels applied
+- [ ] Appropriate contributors tagged
+- [ ] Contributor assigned/self-assigned
diff --git a/.gitignore b/.gitignore
@@ -56,3 +56,9 @@ test/fuzz/**/corpus
 test/fuzz/**/crashers
 test/fuzz/**/suppressions
 test/fuzz/**/*.zip
+*.aux
+*.bbl
+*.blg
+*.pdf
+*.gz
+*.dvi
diff --git a/.markdownlint.yml b/.markdownlint.yml
@@ -1,8 +1,11 @@
-default: true,
-MD007: { "indent": 4 }
+default: true
+MD001: false
+MD007: {indent: 4}
 MD013: false
-MD024: { siblings_only: true }
+MD024: {siblings_only: true}
 MD025: false
-MD033: { no-inline-html: false }
-no-hard-tabs: false
-whitespace: false
+MD033: false
+MD036: false
+MD010: false
+MD012: false
+MD028: false
diff --git a/proto/README.md b/proto/README.md
@@ -0,0 +1,23 @@
+# Protocol Buffers
+
+This sections defines the types and messages shared across implementations. The definition of the data structures are located in the [core/data_structures](../spec/core/data_structures.md) for the core data types and ABCI definitions are located in the [ABCI](../spec/abci/README.md) section.
+
+## Process of Updates
+
+The `.proto` files within this section are core to the protocol and updates must be treated as such.
+
+### Steps
+
+1. Make an issue with the proposed change.
+   - Within in the issue members from both the Tendermint-go and Tendermint-rs team will leave comments. If there is not consensus on the change an [RFC](../rfc/README.md) may be requested.
+  1a. Submission of an RFC as a pull request should be made to facilitate further discussion.
+  1b. Merge the RFC.
+2. Make the necessary changes to the `.proto` file(s), [core data structures](../spec/core/data_structures.md) and/or [ABCI protocol](../spec/abci/apps.md).
+3. Open issues within Tendermint-go and Tendermint-rs repos. This is used to notify the teams that a change occurred in the spec.
+   1. Tag the issue with a spec version label. This will notify the team the changed has been made on master but has not entered a release.
+
+### Versioning
+
+The spec repo aims to be versioned. Once it has been versioned, updates to the protobuf files will live on master. After a certain amount of time, decided on by Tendermint-go and Tendermint-rs team leads, a release will be made on the spec repo. The spec may contain minor releases as well, depending on the implementation these changes may lead to a breaking change. If so, the implementation team should open an issue within the spec repo requiring a major release of the spec.
+
+If the steps above were followed each implementation should have issues tagged with a spec change label. Once all issues have been completed the team should signify their readiness for release.
diff --git a/spec/README.md b/spec/README.md
@@ -0,0 +1,93 @@
+---
+order: 1
+title: Overview
+parent:
+  title: Spec
+  order: 7
+---
+
+# Tendermint Spec
+
+This is a markdown specification of the Tendermint blockchain.
+It defines the base data structures, how they are validated,
+and how they are communicated over the network.
+
+If you find discrepancies between the spec and the code that
+do not have an associated issue or pull request on github,
+please submit them to our [bug bounty](https://tendermint.com/security)!
+
+## Contents
+
+- [Overview](#overview)
+
+### Data Structures
+
+- [Encoding and Digests](./core/encoding.md)
+- [Blockchain](./core/data_structures.md)
+- [State](./core/state.md)
+
+### Consensus Protocol
+
+- [Consensus Algorithm](./consensus/consensus.md)
+- [Creating a proposal](./consensus/creating-proposal.md)
+- [Time](./consensus/bft-time.md)
+- [Light-Client](./consensus/light-client/README.md)
+
+### P2P and Network Protocols
+
+- [The Base P2P Layer](./p2p/node.md): multiplex the protocols ("reactors") on authenticated and encrypted TCP connections
+- [Peer Exchange (PEX)](./p2p/messages/pex.md): gossip known peer addresses so peers can find each other
+- [Block Sync](./p2p/messages/block-sync.md): gossip blocks so peers can catch up quickly
+- [Consensus](./p2p/messages/consensus.md): gossip votes and block parts so new blocks can be committed
+- [Mempool](./p2p/messages/mempool.md): gossip transactions so they get included in blocks
+- [Evidence](./p2p/messages/evidence.md): sending invalid evidence will stop the peer
+
+### RPC
+
+- [RPC SPEC](./rpc/README.md): Specification of the Tendermint remote procedure call interface.
+
+### Software
+
+- [ABCI](./abci/README.md): Details about interactions between the
+  application and consensus engine over ABCI
+- [Write-Ahead Log](./consensus/wal.md): Details about how the consensus
+  engine preserves data and recovers from crash failures
+
+## Overview
+
+Tendermint provides Byzantine Fault Tolerant State Machine Replication using
+hash-linked batches of transactions. Such transaction batches are called "blocks".
+Hence, Tendermint defines a "blockchain".
+
+Each block in Tendermint has a unique index - its Height.
+Height's in the blockchain are monotonic.
+Each block is committed by a known set of weighted Validators.
+Membership and weighting within this validator set may change over time.
+Tendermint guarantees the safety and liveness of the blockchain
+so long as less than 1/3 of the total weight of the Validator set
+is malicious or faulty.
+
+A commit in Tendermint is a set of signed messages from more than 2/3 of
+the total weight of the current Validator set. Validators take turns proposing
+blocks and voting on them. Once enough votes are received, the block is considered
+committed. These votes are included in the _next_ block as proof that the previous block
+was committed - they cannot be included in the current block, as that block has already been
+created.
+
+Once a block is committed, it can be executed against an application.
+The application returns results for each of the transactions in the block.
+The application can also return changes to be made to the validator set,
+as well as a cryptographic digest of its latest state.
+
+Tendermint is designed to enable efficient verification and authentication
+of the latest state of the blockchain. To achieve this, it embeds
+cryptographic commitments to certain information in the block "header".
+This information includes the contents of the block (eg. the transactions),
+the validator set committing the block, as well as the various results returned by the application.
+Note, however, that block execution only occurs _after_ a block is committed.
+Thus, application results can only be included in the _next_ block.
+
+Also note that information like the transaction results and the validator set are never
+directly included in the block - only their cryptographic digests (Merkle roots) are.
+Hence, verification of a block requires a separate data structure to store this information.
+We call this the `State`. Block verification also requires access to the previous block.
diff --git a/spec/abci/README.md b/spec/abci/README.md
@@ -0,0 +1,27 @@
+---
+order: 1
+parent:
+  title: ABCI
+  order: 2
+---
+
+# ABCI
+
+ABCI stands for "**A**pplication **B**lock**c**hain **I**nterface".
+ABCI is the interface between Tendermint (a state-machine replication engine)
+and your application (the actual state machine). It consists of a set of
+_methods_, each with a corresponding `Request` and `Response`message type. 
+To perform state-machine replication, Tendermint calls the ABCI methods on the 
+ABCI application by sending the `Request*` messages and receiving the `Response*` messages in return.
+
+All ABCI messages and methods are defined in [protocol buffers](https://github.com/tendermint/spec/blob/master/proto/abci/types.proto). 
+This allows Tendermint to run with applications written in many programming languages.
+
+This specification is split as follows:
+
+- [Methods and Types](./abci.md) - complete details on all ABCI methods and
+  message types
+- [Applications](./apps.md) - how to manage ABCI application state and other
+  details about building ABCI applications
+- [Client and Server](./client-server.md) - for those looking to implement their
+  own ABCI application servers