diff --git a/rust-spec/fastsync/README.md b/rust-spec/fastsync/README.md index ebb0086c2..0f96d6a90 100644 --- a/rust-spec/fastsync/README.md +++ b/rust-spec/fastsync/README.md @@ -1,3 +1,3 @@ # Fast Sync -Deprecated see [tendermint/tendermint/docs/tendermint-core/fastsync.md](https://github.com/tendermint/tendermint/blob/master/docs/tendermint-core/fast-sync.md) +Deprecated see [tendermint/docs/tendermint-core/block-sync](https://github.com/tendermint/tendermint/blob/master/docs/tendermint-core/block-sync/README.md) diff --git a/spec/abci/README.md b/spec/abci/README.md index 61b7b4b7f..c356165af 100644 --- a/spec/abci/README.md +++ b/spec/abci/README.md @@ -10,11 +10,11 @@ parent: 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 +_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/tendermint/abci/types.proto). +All ABCI messages and methods are defined in [protocol buffers](../../proto/tendermint/abci/types.proto). This allows Tendermint to run with applications written in many programming languages. This specification is split as follows: diff --git a/spec/abci/abci.md b/spec/abci/abci.md index edcb4ff83..5d0332a2e 100644 --- a/spec/abci/abci.md +++ b/spec/abci/abci.md @@ -79,7 +79,7 @@ Tendermint consensus. ### Query The `Query` ABCI method query queries the application for information about application state. -When Tendermint receives a `ResponseQuery` with a non-zero `Code`, this code is +When Tendermint receives a `ResponseQuery` with a non-zero `Code`, this code is returned directly to the client that initiated the query. ## Events @@ -91,7 +91,7 @@ transactions and blocks this metadata relates to. Events returned via these ABCI methods do not impact Tendermint consensus in any way and instead exist to power subscriptions and queries of Tendermint state. -An `Event` contains a `type` and a list of `EventAttributes`, which are key-value +An `Event` contains a `type` and a list of `EventAttributes`, which are key-value string pairs denoting metadata about what happened during the method's execution. `Event` values can be used to index transactions and blocks according to what happened during their execution. Note that the set of events returned for a block from @@ -163,8 +163,8 @@ Example: Tendermint's security model relies on the use of "evidence". Evidence is proof of malicious behaviour by a network participant. It is the responsibility of Tendermint to detect such malicious behaviour. When malicious behavior is detected, Tendermint -will gossip evidence of the behavior to other nodes and commit the evidence to -the chain once it is verified by all validators. This evidence will then be +will gossip evidence of the behavior to other nodes and commit the evidence to +the chain once it is verified by all validators. This evidence will then be passed it on to the application through the ABCI. It is the responsibility of the application to handle the evidence and exercise punishment. @@ -179,8 +179,8 @@ enum EvidenceType { ``` There are two forms of evidence: Duplicate Vote and Light Client Attack. More -information can be found in either [data structures](https://github.com/tendermint/spec/blob/master/spec/core/data_structures.md) -or [accountability](https://github.com/tendermint/spec/blob/master/spec/light-client/accountability/) +information can be found in either [data structures](../core/data_structures.md) +or [accountability](../light-client/accountability/README.md) ## Determinism @@ -246,7 +246,7 @@ Commit are included in the header of the next block. State sync allows new nodes to rapidly bootstrap by discovering, fetching, and applying state machine snapshots instead of replaying historical blocks. For more details, see the -[state sync section](../spec/p2p/messages/state-sync.md). +[state sync section](../p2p/messages/state-sync.md). New nodes will discover and request snapshots from other nodes in the P2P network. A Tendermint node that receives a request for snapshots from a peer will call @@ -263,7 +263,7 @@ the `LoadSnapshotChunk` method. As the new node receives "chunks" it will apply them sequentially to the local application with `ApplySnapshotChunk`. When all chunks have been applied, the application `AppHash` is retrieved via an `Info` query. The `AppHash` is then compared to -the blockchain's `AppHash` which is verified via [light client verification](../spec/light-client/verification/README.md). +the blockchain's `AppHash` which is verified via [light client verification](../light-client/verification/README.md). ## Messages @@ -297,7 +297,7 @@ the blockchain's `AppHash` which is verified via [light client verification](../ | abci_version | string | The Tendermint ABCI semantic version | 4 | * **Response**: - + | Name | Type | Description | Field Number | |---------------------|--------|--------------------------------------------------|--------------| | data | string | Some arbitrary information | 1 | @@ -351,7 +351,7 @@ the blockchain's `AppHash` which is verified via [light client verification](../ ### Query * **Request**: - + | Name | Type | Description | Field Number | |--------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| | data | bytes | Raw query bytes. Can be used with or in lieu of Path. | 1 | @@ -495,7 +495,7 @@ the blockchain's `AppHash` which is verified via [light client verification](../ * `H+3`: `LastCommitInfo` is changed to include the altered validator set. * `consensus_param_updates` returned for block `H` apply to the consensus params for block `H+1`. For more information on the consensus parameters, - see the [application spec entry on consensus parameters](../spec/abci/apps.md#consensus-parameters). + see the [application spec entry on consensus parameters](./apps.md#consensus-parameters). ### Commit @@ -605,7 +605,7 @@ the blockchain's `AppHash` which is verified via [light client verification](../ can be spoofed by adversaries, so applications should employ additional verification schemes to avoid denial-of-service attacks. The verified `AppHash` is automatically checked against the restored application at the end of snapshot restoration. - * For more information, see the `Snapshot` data type or the [state sync section](../spec/p2p/messages/state-sync.md). + * For more information, see the `Snapshot` data type or the [state sync section](../p2p/messages/state-sync.md). ### ApplySnapshotChunk @@ -651,7 +651,7 @@ the blockchain's `AppHash` which is verified via [light client verification](../ ## Data Types -Most of the data structures used in ABCI are shared [common data structures](../spec/core/data_structures.md). In certain cases, ABCI uses different data structures which are documented here: +Most of the data structures used in ABCI are shared [common data structures](../core/data_structures.md). In certain cases, ABCI uses different data structures which are documented here: ### Validator @@ -769,7 +769,7 @@ Most of the data structures used in ABCI are shared [common data structures](../ | metadata | bytes | Arbitrary application metadata, for example chunk hashes or other verification data. | 3 | * **Usage**: - * Used for state sync snapshots, see the [state sync section](../spec/p2p/messages/state-sync.md) for details. + * Used for state sync snapshots, see the [state sync section](../p2p/messages/state-sync.md) for details. * A snapshot is considered identical across nodes only if _all_ fields are equal (including `Metadata`). Chunks may be retrieved from all nodes that have the same snapshot. * When sent across the network, a snapshot message can be at most 4 MB. diff --git a/spec/abci/apps.md b/spec/abci/apps.md index d1b85a740..030a3d3c3 100644 --- a/spec/abci/apps.md +++ b/spec/abci/apps.md @@ -166,9 +166,10 @@ the difference credited back. Tendermint adopts a similar abstraction, though uses it only optionally and weakly, allowing applications to define their own sense of the cost of execution. -In Tendermint, the [ConsensusParams.Block.MaxGas](../proto/types/params.proto) limits the amount of `gas` that can be used in a block. -The default value is `-1`, meaning no limit, or that the concept of gas is -meaningless. +In Tendermint, the +[ConsensusParams.Block.MaxGas](../../proto/tendermint/types/params.proto) +limits the amount of `gas` that can be used in a block. The default value is +`-1`, meaning no limit, or that the concept of gas is meaningless. Responses contain a `GasWanted` and `GasUsed` field. The former is the maximum amount of gas the sender of a tx is willing to use, and the later is how much it actually @@ -217,7 +218,7 @@ the Tendermint protocol. If DeliverTx returns `Code != 0`, the transaction will be considered invalid, though it is still included in the block. -DeliverTx also returns a [Code, Data, and Log](../../proto/abci/types.proto#L189-L191). +DeliverTx also returns a [Code, Data, and Log](../../proto/tendermint/abci/types.proto#L189-L191). `Data` contains the result of the CheckTx transaction execution, if any. It is semantically meaningless to Tendermint. diff --git a/spec/abci/client-server.md b/spec/abci/client-server.md index 78c226743..912270e66 100644 --- a/spec/abci/client-server.md +++ b/spec/abci/client-server.md @@ -14,7 +14,7 @@ Applications](./apps.md). ## Message Protocol The message protocol consists of pairs of requests and responses defined in the -[protobuf file](https://github.com/tendermint/tendermint/blob/master/proto/tendermint/abci/types.proto). +[protobuf file](../../proto/tendermint/abci/types.proto). Some messages have no fields, while others may include byte-arrays, strings, integers, or custom protobuf types. @@ -54,13 +54,13 @@ If GRPC is available in your language, this is the easiest approach, though it will have significant performance overhead. To get started with GRPC, copy in the [protobuf -file](https://github.com/tendermint/tendermint/blob/master/proto/tendermint/abci/types.proto) -and compile it using the GRPC plugin for your language. For instance, -for golang, the command is `protoc --go_out=plugins=grpc:. types.proto`. -See the [grpc documentation for more details](http://www.grpc.io/docs/). -`protoc` will autogenerate all the necessary code for ABCI client and -server in your language, including whatever interface your application -must satisfy to be used by the ABCI server for handling requests. +file](../../proto/tendermint/abci/types.proto) and compile it using the GRPC +plugin for your language. For instance, for golang, the command is `protoc +--go_out=plugins=grpc:. types.proto`. See the [grpc documentation for more +details](http://www.grpc.io/docs/). `protoc` will autogenerate all the +necessary code for ABCI client and server in your language, including whatever +interface your application must satisfy to be used by the ABCI server for +handling requests. Note the length-prefixing used in the socket implementation (TSP) does not apply for GRPC. diff --git a/spec/consensus/light-client/accountability.md b/spec/consensus/light-client/accountability.md index 5cf46b0b4..6684021d6 100644 --- a/spec/consensus/light-client/accountability.md +++ b/spec/consensus/light-client/accountability.md @@ -1,3 +1,3 @@ # Fork accountability -Deprecated, please see [light-client/accountability](../../light-client/accountability.md). +Deprecated, please see [light-client/accountability](../../light-client/accountability/README.md). diff --git a/spec/consensus/light-client/detection.md b/spec/consensus/light-client/detection.md index 5c87562ba..484f6094b 100644 --- a/spec/consensus/light-client/detection.md +++ b/spec/consensus/light-client/detection.md @@ -1,3 +1,3 @@ # Detection -Deprecated, please see [light-client/detection](../../light-client/detection.md). +Deprecated, please see [light-client/detection](../../light-client/detection/README.md). diff --git a/spec/consensus/light-client/verification.md b/spec/consensus/light-client/verification.md index 1f0104a40..7f3ab4718 100644 --- a/spec/consensus/light-client/verification.md +++ b/spec/consensus/light-client/verification.md @@ -1,3 +1,3 @@ # Core Verification -Deprecated, please see [light-client/accountability](../../light-client/verification.md). +Deprecated, please see [light-client/accountability](../../light-client/verification/README.md). diff --git a/spec/consensus/proposer-based-timestamp/pbts_001_draft.md b/spec/consensus/proposer-based-timestamp/pbts_001_draft.md index a4d876b28..b8747aabd 100644 --- a/spec/consensus/proposer-based-timestamp/pbts_001_draft.md +++ b/spec/consensus/proposer-based-timestamp/pbts_001_draft.md @@ -1,3 +1,5 @@ + + # Proposer-Based Time ## Current BFTTime diff --git a/spec/consensus/readme.md b/spec/consensus/readme.md index aa79ba192..4e13b7a9b 100644 --- a/spec/consensus/readme.md +++ b/spec/consensus/readme.md @@ -26,7 +26,7 @@ Specification of the Tendermint consensus protocol. consensus state machine to recover from crashes. The protocol used to gossip consensus messages between peers, which is critical -for liveness, is described in the [reactors section](../reactors/consensus/consensus.md). +for liveness, is described in the [reactors section](./consensus.md). There is also a [stale markdown description](consensus.md) of the consensus state machine (TODO update this). diff --git a/spec/light-client/README.md b/spec/light-client/README.md index 42f20d46c..2cf888a9d 100644 --- a/spec/light-client/README.md +++ b/spec/light-client/README.md @@ -4,6 +4,7 @@ parent: title: Light Client order: 5 --- + # Light Client Specification diff --git a/spec/light-client/attacks/isolate-attackers_001_draft.md b/spec/light-client/attacks/isolate-attackers_001_draft.md index e4f585f4a..7a374f113 100644 --- a/spec/light-client/attacks/isolate-attackers_001_draft.md +++ b/spec/light-client/attacks/isolate-attackers_001_draft.md @@ -1,3 +1,4 @@ + # Lightclient Attackers Isolation diff --git a/spec/light-client/attacks/isolate-attackers_002_reviewed.md b/spec/light-client/attacks/isolate-attackers_002_reviewed.md index febcc10a8..482fec335 100644 --- a/spec/light-client/attacks/isolate-attackers_002_reviewed.md +++ b/spec/light-client/attacks/isolate-attackers_002_reviewed.md @@ -1,3 +1,5 @@ + + # Lightclient Attackers Isolation Adversarial nodes may have the incentive to lie to a lightclient about the state of a Tendermint blockchain. An attempt to do so is called attack. Light client [verification][verification] checks incoming data by checking a so-called "commit", which is a forwarded set of signed messages that is (supposedly) produced during executing Tendermint consensus. Thus, an attack boils down to creating and signing Tendermint consensus messages in deviation from the Tendermint consensus algorithm rules. diff --git a/spec/light-client/detection/README.md b/spec/light-client/detection/README.md index 50d8ab6fe..f9c0820c0 100644 --- a/spec/light-client/detection/README.md +++ b/spec/light-client/detection/README.md @@ -14,7 +14,7 @@ This directory captures the ongoing work and discussion on fork detection both in the context of a Tendermint light node and in the context of IBC. It contains the following files -### [detection.md](./detection.md) +### detection.md a draft of the light node fork detection including "proof of fork" definition, that is, the data structure to submit evidence to full diff --git a/spec/light-client/detection/detection_001_reviewed.md b/spec/light-client/detection/detection_001_reviewed.md index db8c29a14..cebf9aebb 100644 --- a/spec/light-client/detection/detection_001_reviewed.md +++ b/spec/light-client/detection/detection_001_reviewed.md @@ -1,3 +1,5 @@ + + # ***This an unfinished draft. Comments are welcome!*** **TODO:** We will need to do small adaptations to the verification diff --git a/spec/light-client/detection/detection_003_reviewed.md b/spec/light-client/detection/detection_003_reviewed.md index 13f6e9716..ae00cba06 100644 --- a/spec/light-client/detection/detection_003_reviewed.md +++ b/spec/light-client/detection/detection_003_reviewed.md @@ -1,3 +1,5 @@ + + # Light Client Attack Detector In this specification, we strengthen the light client to be resistant diff --git a/spec/light-client/detection/req-ibc-detection.md b/spec/light-client/detection/req-ibc-detection.md index 439ca26b6..da5dc7a2a 100644 --- a/spec/light-client/detection/req-ibc-detection.md +++ b/spec/light-client/detection/req-ibc-detection.md @@ -1,3 +1,5 @@ + + # Requirements for Fork Detection in the IBC Context ## What you need to know about IBC diff --git a/spec/light-client/supervisor/supervisor_001_draft.md b/spec/light-client/supervisor/supervisor_001_draft.md index 90add66fc..eb43f6034 100644 --- a/spec/light-client/supervisor/supervisor_001_draft.md +++ b/spec/light-client/supervisor/supervisor_001_draft.md @@ -1,3 +1,5 @@ + + # Draft of Light Client Supervisor for discussion ## TODOs @@ -634,4 +636,4 @@ func VerifyAndDetect (lightStore LightStore, targetHeight Height) - an attack is detected - [LC-DATA-PEERLIST-INV.1] is violated ----- \ No newline at end of file +---- diff --git a/spec/light-client/verification/README.md b/spec/light-client/verification/README.md index 8777374ac..8787d0725 100644 --- a/spec/light-client/verification/README.md +++ b/spec/light-client/verification/README.md @@ -27,7 +27,7 @@ Given a known bound `TRUSTED_PERIOD`, and a block `b` with header `h` generated in `validators(b.Header.NextValidatorsHash)` is correct until time `b.Header.Time + TRUSTED_PERIOD`. *Assumption*: "correct" is defined w.r.t. realtime (some Newtonian global notion of time, i.e., wall time), -while `Header.Time` corresponds to the [BFT time](../consensus/bft-time.md). In this note, we assume that clocks of correct processes +while `Header.Time` corresponds to the [BFT time](../../consensus/bft-time.md). In this note, we assume that clocks of correct processes are synchronized (for example using NTP), and therefore there is bounded clock drift (`CLOCK_DRIFT`) between local clocks and BFT time. More precisely, for every correct light client process and every `header.Time` (i.e. BFT Time, for a header correctly generated by the Tendermint consensus), the following inequality holds: `Header.Time < now + CLOCK_DRIFT`, @@ -47,7 +47,7 @@ Mechanisms like `fork accountability` and `evidence submission` are defined in t they incentivize validators to follow the protocol specification defined in this document. If they don't, and we have 1/3 (or more) faulty validators, safety may be violated. Our approach then is to *detect* these cases (after the fact), and take suitable repair actions (automatic and social). -This is discussed in document on [Fork accountability](./accountability.md). +This is discussed in document on [Fork accountability](../accountability/README.md). The term "trusted" above indicates that the correctness of the protocol depends on this assumption. It is in the responsibility of the user that runs the light client to make sure that the risk diff --git a/spec/light-client/verification/verification_001_published.md b/spec/light-client/verification/verification_001_published.md index 90dacc749..493098a82 100644 --- a/spec/light-client/verification/verification_001_published.md +++ b/spec/light-client/verification/verification_001_published.md @@ -1,3 +1,5 @@ + + # Light Client Verification The light client implements a read operation of a @@ -1175,4 +1177,4 @@ func Main (primary PeerID, lightStore LightStore, targetHeight Height) [FN-ManifestFaulty-link]: https://github.com/tendermint/spec/blob/master/spec/blockchain/fullnode.md#fn-manifestfaulty -[arXiv]: https://arxiv.org/abs/1807.04938 \ No newline at end of file +[arXiv]: https://arxiv.org/abs/1807.04938 diff --git a/spec/light-client/verification/verification_002_draft.md b/spec/light-client/verification/verification_002_draft.md index 9047eb417..70cdfdd94 100644 --- a/spec/light-client/verification/verification_002_draft.md +++ b/spec/light-client/verification/verification_002_draft.md @@ -1,3 +1,5 @@ + + # Light Client Verification The light client implements a read operation of a diff --git a/spec/p2p/messages/state-sync.md b/spec/p2p/messages/state-sync.md index 71e3ae71b..2aa5618bc 100644 --- a/spec/p2p/messages/state-sync.md +++ b/spec/p2p/messages/state-sync.md @@ -91,8 +91,9 @@ if necessary. The light block at the height of the snapshot will be used to veri |---------------|---------------------------------------------------------|--------------------------------------|--------------| | light_block | [LightBlock](../../core/data_structures.md#lightblock) | Light block at the height requested | 1 | -State sync will use [light client verification](../../light-client/verification.README.md) to verify -the light blocks. +State sync will use [light client +verification](https://github.com/tendermint/tendermint/blob/master/docs/tendermint-core/light-client.md) +to verify the light blocks. If no state sync is in progress (i.e. during normal operation), any unsolicited response messages diff --git a/spec/p2p/node.md b/spec/p2p/node.md index 0bbcf0b5b..e056c14af 100644 --- a/spec/p2p/node.md +++ b/spec/p2p/node.md @@ -12,8 +12,6 @@ Seeds should operate full nodes with the PEX reactor in a "crawler" mode that continuously explores to validate the availability of peers. Seeds should only respond with some top percentile of the best peers it knows about. -See [the peer-exchange docs](https://github.com/tendermint/spec/blob/master/spec/reactors/pex/pex.md) for - details on peer quality. ## New Full Node diff --git a/spec/p2p/peer.md b/spec/p2p/peer.md index 52d00b584..292cbebfa 100644 --- a/spec/p2p/peer.md +++ b/spec/p2p/peer.md @@ -2,7 +2,7 @@ This document explains how Tendermint Peers are identified and how they connect to one another. -For details on peer discovery, see the [peer exchange (PEX) reactor doc](https://github.com/tendermint/spec/blob/master/spec/reactors/pex/pex.md). +For details on peer discovery, see the [peer exchange (PEX) doc](https://github.com/tendermint/tendermint/blob/master/docs/tendermint-core/pex/README.md). ## Peer Identity