From 158a546bba3c6e9f95a52366c38323f711bf5ca0 Mon Sep 17 00:00:00 2001 From: Andy Nogueira Date: Fri, 19 Jan 2024 15:20:09 -0500 Subject: [PATCH 1/7] new branch, re-creating tutorials (#1613) --- README.md | 4 ++-- docs/guides/README.md | 12 ----------- docs/tutorials/README.md | 26 +++++++++++++++++++++++ docs/{guides => tutorials}/go-built-in.md | 2 +- docs/{guides => tutorials}/go.md | 2 +- docs/{guides => tutorials}/install.md | 0 docs/{guides => tutorials}/quick-start.md | 4 ++-- 7 files changed, 32 insertions(+), 18 deletions(-) delete mode 100644 docs/guides/README.md create mode 100644 docs/tutorials/README.md rename docs/{guides => tutorials}/go-built-in.md (99%) rename docs/{guides => tutorials}/go.md (99%) rename docs/{guides => tutorials}/install.md (100%) rename docs/{guides => tutorials}/quick-start.md (98%) diff --git a/README.md b/README.md index dad864f6fd6..5813bec08ea 100644 --- a/README.md +++ b/README.md @@ -70,11 +70,11 @@ Please see [SECURITY.md](./SECURITY.md). ### Install -See the [install guide](./docs/guides/install.md). +See the [install guide](docs/tutorials/install.md). ### Quick Start -- [Single node](./docs/guides/quick-start.md) +- [Single node](docs/tutorials/quick-start.md) - [Local cluster using docker-compose](./docs/networks/docker-compose.md) ## Contributing diff --git a/docs/guides/README.md b/docs/guides/README.md deleted file mode 100644 index b563396313a..00000000000 --- a/docs/guides/README.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -order: false -parent: - order: 2 ---- - -# Guides - -- [Installing CometBFT](./install.md) -- [Quick-start using CometBFT](./quick-start.md) -- [Creating a built-in application in Go](./go-built-in.md) -- [Creating an external application in Go](./go.md) diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md new file mode 100644 index 00000000000..ba6aaee59e9 --- /dev/null +++ b/docs/tutorials/README.md @@ -0,0 +1,26 @@ +--- +order: 1 +title: Tutorials +description: Tutorials +parent: + order: 1 +--- + +# Welcome to CometBFT Tutorials + +Are you ready to explore the world of CometBFT, the cutting-edge consensus algorithm that's revolutionizing the field of distributed systems? You've come to the right place! Our CometBFT Tutorials provide the knowledge and hands-on experience you need to master this groundbreaking technology. + +## Why Choose CometBFT Tutorials? + +- Comprehensive Learning: Our tutorials cover everything from the basics of consensus algorithms to advanced topics in CometBFT, ensuring that both beginners and experts can benefit. +- Hands-On Experience: We believe in learning by doing. Our tutorials include practical examples and exercises that allow you to implement CometBFT in real-world scenarios. +- Up-to-date Content: We keep our tutorials up-to-date with the latest developments in CometBFT, ensuring that you have access to the most current information and best practices. + Get Started Today! + +Whether you're a chain developer, an integrator, an operator, or simply curious about distributed systems, our CometBFT Tutorials are the perfect resource to enhance your knowledge and skills. + +Ready to begin? Start exploring our tutorials now and embark on a learning experience that will empower you to harness the power of CometBFT for your projects and applications. Let's build a more reliable and resilient future together with CometBFT! +- [Installing CometBFT](./install.md) +- [Quick-start using CometBFT](./quick-start.md) +- [Creating a built-in application in Go](./go-built-in.md) +- [Creating an external application in Go](./go.md) diff --git a/docs/guides/go-built-in.md b/docs/tutorials/go-built-in.md similarity index 99% rename from docs/guides/go-built-in.md rename to docs/tutorials/go-built-in.md index b2cd7f2d7c9..093fba394f6 100644 --- a/docs/guides/go-built-in.md +++ b/docs/tutorials/go-built-in.md @@ -38,7 +38,7 @@ This is the approach followed in this tutorial. On the other hand, having a separate application might give you better security guarantees as two processes would be communicating via established binary protocol. CometBFT will not have access to application's state. -If that is the way you wish to proceed, use the [Creating an application in Go](./go.md) guide instead of this one. +If that is the way you wish to proceed, use the [Creating an application in Go](go.md) guide instead of this one. ## 1.1 Installing Go diff --git a/docs/guides/go.md b/docs/tutorials/go.md similarity index 99% rename from docs/guides/go.md rename to docs/tutorials/go.md index 923dbd4866d..bc827be78b3 100644 --- a/docs/guides/go.md +++ b/docs/tutorials/go.md @@ -33,7 +33,7 @@ On the one hand, to get maximum performance you can run your application in the same process as the CometBFT, as long as your application is written in Go. [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) is written this way. -If that is the way you wish to proceed, use the [Creating a built-in application in Go](./go-built-in.md) guide instead of this one. +If that is the way you wish to proceed, use the [Creating a built-in application in Go](go-built-in.md) guide instead of this one. On the other hand, having a separate application might give you better security guarantees as two processes would be communicating via established binary protocol. diff --git a/docs/guides/install.md b/docs/tutorials/install.md similarity index 100% rename from docs/guides/install.md rename to docs/tutorials/install.md diff --git a/docs/guides/quick-start.md b/docs/tutorials/quick-start.md similarity index 98% rename from docs/guides/quick-start.md rename to docs/tutorials/quick-start.md index d5f1481710c..4f21165adc8 100644 --- a/docs/guides/quick-start.md +++ b/docs/tutorials/quick-start.md @@ -11,7 +11,7 @@ works and want to get started right away, continue. ## Install -See the [install guide](./install.md). +See the [install guide](install.md). ## Initialization @@ -95,7 +95,7 @@ First create four Ubuntu cloud machines. The following was tested on Digital Ocean Ubuntu 16.04 x64 (3GB/1CPU, 20GB SSD). We'll refer to their respective IP addresses below as IP1, IP2, IP3, IP4. -Then, `ssh` into each machine and install CometBFT following the [instructions](./install.md). +Then, `ssh` into each machine and install CometBFT following the [instructions](install.md). Next, use the `cometbft testnet` command to create four directories of config files (found in `./mytestnet`) and copy each directory to the relevant machine in the cloud, so that each machine has `$HOME/mytestnet/node[0-3]` directory. From fdf5d239c1bf2e98e6f5a23c177361bee39fdbc8 Mon Sep 17 00:00:00 2001 From: Andy Nogueira Date: Fri, 19 Jan 2024 16:42:33 -0500 Subject: [PATCH 2/7] new branch, re-creating references (#1613) --- CHANGELOG.md | 32 +-- CONTRIBUTING.md | 2 +- README.md | 4 +- UPGRADING.md | 2 +- docs/architecture/tendermint-core/README.md | 105 ------- docs/references/README.md | 73 +++++ docs/{ => references}/architecture/README.md | 22 +- .../adr-100-data-companion-push-api.md | 2 +- .../adr-101-data-companion-pull-api.md | 22 +- .../architecture/adr-103-proto-versioning.md | 0 .../adr-104-out-of-band-state-sync.md | 124 ++++----- .../adr-105-refactor-mempool-senders.md | 0 .../adr-107-betaize-proto-versions.md | 0 .../architecture/adr-108-e2e-abci++.md | 170 ++++++------ .../adr-109-reduce-go-api-surface.md | 2 +- .../architecture/adr-110-remote-mempool.md | 2 +- .../architecture/adr-111-nop-mempool.md | 0 .../architecture/adr-template.md | 0 .../architecture/tendermint-core/README.md | 105 +++++++ .../tendermint-core/adr-001-logging.md | 0 .../adr-002-event-subscription.md | 0 .../tendermint-core/adr-003-abci-app-rpc.md | 0 .../adr-004-historical-validators.md | 0 .../adr-005-consensus-params.md | 0 .../tendermint-core/adr-006-trust-metric.md | 0 .../adr-007-trust-metric-usage.md | 0 .../tendermint-core/adr-008-priv-validator.md | 0 .../tendermint-core/adr-009-ABCI-design.md | 0 .../tendermint-core/adr-010-crypto-changes.md | 0 .../tendermint-core/adr-011-monitoring.md | 0 .../tendermint-core/adr-012-peer-transport.md | 0 .../adr-013-symmetric-crypto.md | 0 .../adr-014-secp-malleability.md | 0 .../adr-015-crypto-encoding.md | 0 .../adr-016-protocol-versions.md | 0 .../tendermint-core/adr-017-chain-versions.md | 0 .../adr-018-ABCI-Validators.md | 0 .../tendermint-core/adr-019-multisigs.md | 0 .../tendermint-core/adr-020-block-size.md | 0 .../tendermint-core/adr-021-abci-events.md | 0 .../tendermint-core/adr-022-abci-errors.md | 0 .../adr-023-ABCI-propose-tx.md | 0 .../tendermint-core/adr-024-sign-bytes.md | 0 .../tendermint-core/adr-025-commit.md | 0 .../adr-026-general-merkle-proof.md | 0 .../adr-029-check-tx-consensus.md | 0 .../adr-030-consensus-refactor.md | 0 .../tendermint-core/adr-033-pubsub.md | 0 .../adr-034-priv-validator-file-structure.md | 0 .../tendermint-core/adr-035-documentation.md | 0 .../adr-036-empty-blocks-abci.md | 0 .../tendermint-core/adr-037-deliver-block.md | 0 .../adr-038-non-zero-start-height.md | 0 .../tendermint-core/adr-039-peer-behaviour.md | 0 .../adr-040-blockchain-reactor-refactor.md | 0 .../adr-041-proposer-selection-via-abci.md | 0 .../tendermint-core/adr-042-state-sync.md | 0 .../adr-043-blockchain-riri-org.md | 0 ...-044-lite-client-with-weak-subjectivity.md | 0 .../tendermint-core/adr-045-abci-evidence.md | 0 .../adr-046-light-client-implementation.md | 2 +- ...047-handling-evidence-from-light-client.md | 4 +- .../adr-050-improved-trusted-peering.md | 0 .../adr-051-double-signing-risk-reduction.md | 0 .../adr-052-tendermint-mode.md | 0 .../adr-053-state-sync-prototype.md | 6 +- .../adr-054-crypto-encoding-2.md | 0 .../adr-055-protobuf-design.md | 0 .../adr-056-light-client-amnesia-attacks.md | 2 +- .../tendermint-core/adr-057-RPC.md | 0 .../tendermint-core/adr-058-event-hashing.md | 2 +- ...-059-evidence-composition-and-lifecycle.md | 4 +- .../adr-060-go-api-stability.md | 0 .../adr-061-p2p-refactor-scope.md | 0 .../adr-062-p2p-architecture.md | 0 .../tendermint-core/adr-063-privval-grpc.md | 0 .../adr-064-batch-verification.md | 0 .../adr-065-custom-event-indexing.md | 0 .../tendermint-core/adr-066-e2e-testing.md | 0 .../adr-067-mempool-refactor.md | 2 +- .../tendermint-core/adr-068-reverse-sync.md | 0 .../adr-069-flexible-node-initialization.md | 6 +- .../adr-071-proposer-based-timestamps.md | 0 .../adr-072-request-for-comments.md | 0 .../tendermint-core/adr-073-libp2p.md | 4 +- .../tendermint-core/adr-074-timeout-params.md | 0 .../adr-075-rpc-subscription.md | 4 +- .../adr-076-combine-spec-repo.md | 0 .../adr-077-block-retention.md | 0 .../adr-078-nonzero-genesis.md | 0 .../adr-079-ed25519-verification.md | 0 .../tendermint-core/adr-080-reverse-sync.md | 0 .../tendermint-core/adr-081-protobuf-mgmt.md | 0 .../tendermint-core/img/adr-046-fig1.png | Bin .../img/adr-062-architecture.svg | 0 .../tendermint-core/img/adr-075-log-after.png | Bin .../img/adr-075-log-before.png | Bin .../img/bc-reactor-refactor.png | Bin .../tendermint-core/img/bc-reactor.png | Bin .../tendermint-core/img/bifurcation-point.png | Bin .../tendermint-core/img/block-retention.png | Bin .../img/blockchain-reactor-v1.png | Bin .../img/blockchain-reactor-v2.png | Bin .../img/blockchain-v2-channels.png | Bin .../img/consensus_blockchain.png | Bin .../img/evidence_lifecycle.png | Bin .../tendermint-core/img/formula1.png | Bin .../tendermint-core/img/formula2.png | Bin .../img/light-client-detector.png | Bin .../tendermint-core/img/mempool-v0.jpeg | Bin .../tendermint-core/img/pbts-message.png | Bin .../tendermint-core/img/state-sync.png | Bin .../tendermint-core/img/tags1.png | Bin .../tendermint-core/img/tm-amnesia-attack.png | Bin docs/{ => references}/qa/CometBFT-QA-34.md | 0 docs/{ => references}/qa/CometBFT-QA-37.md | 0 docs/{ => references}/qa/CometBFT-QA-38.md | 8 +- docs/{ => references}/qa/README.md | 2 +- docs/{ => references}/qa/TMCore-QA-34.md | 0 docs/{ => references}/qa/TMCore-QA-37.md | 0 .../qa/img34/baseline/avg_cpu.png | Bin .../qa/img34/baseline/avg_memory.png | Bin .../qa/img34/baseline/avg_mempool_size.png | Bin .../qa/img34/baseline/block_rate_regular.png | Bin .../qa/img34/baseline/cpu.png | Bin .../qa/img34/baseline/memory.png | Bin .../qa/img34/baseline/mempool_size.png | Bin .../qa/img34/baseline/peers.png | Bin .../qa/img34/baseline/rounds.png | Bin .../img34/baseline/total_txs_rate_regular.png | Bin .../qa/img34/cmt1tm1/all_experiments.png | Bin .../qa/img34/cmt1tm1/avg_cpu.png | Bin .../qa/img34/cmt1tm1/avg_memory.png | Bin .../qa/img34/cmt1tm1/avg_mempool_size.png | Bin .../qa/img34/cmt1tm1/block_rate_regular.png | Bin .../{ => references}/qa/img34/cmt1tm1/cpu.png | Bin .../qa/img34/cmt1tm1/memory.png | Bin .../qa/img34/cmt1tm1/mempool_size.png | Bin .../qa/img34/cmt1tm1/peers.png | Bin .../qa/img34/cmt1tm1/rounds.png | Bin .../img34/cmt1tm1/total_txs_rate_regular.png | Bin .../qa/img34/cmt2tm1/all_experiments.png | Bin .../qa/img34/cmt2tm1/avg_cpu.png | Bin .../qa/img34/cmt2tm1/avg_memory.png | Bin .../qa/img34/cmt2tm1/avg_mempool_size.png | Bin .../qa/img34/cmt2tm1/block_rate_regular.png | Bin .../{ => references}/qa/img34/cmt2tm1/cpu.png | Bin .../qa/img34/cmt2tm1/memory.png | Bin .../qa/img34/cmt2tm1/mempool_size.png | Bin .../qa/img34/cmt2tm1/peers.png | Bin .../qa/img34/cmt2tm1/rounds.png | Bin .../img34/cmt2tm1/total_txs_rate_regular.png | Bin .../qa/img34/homogeneous/all_experiments.png | Bin .../qa/img34/homogeneous/avg_cpu.png | Bin .../qa/img34/homogeneous/avg_memory.png | Bin .../qa/img34/homogeneous/avg_mempool_size.png | Bin .../img34/homogeneous/block_rate_regular.png | Bin .../qa/img34/homogeneous/cpu.png | Bin .../qa/img34/homogeneous/memory.png | Bin .../qa/img34/homogeneous/mempool_size.png | Bin .../qa/img34/homogeneous/peers.png | Bin .../qa/img34/homogeneous/rounds.png | Bin .../homogeneous/total_txs_rate_regular.png | Bin .../qa/img34/v034_200node_latencies.png | Bin .../img34/v034_200node_latencies_zoomed.png | Bin .../v034_200node_tm2cmt1/all_experiments.png | Bin .../qa/img34/v034_200node_tm2cmt1/avg_cpu.png | Bin .../img34/v034_200node_tm2cmt1/avg_memory.png | Bin .../v034_200node_tm2cmt1/avg_mempool_size.png | Bin .../block_rate_regular.png | Bin .../v034_200node_tm2cmt1/c2r200_merged.png | Bin .../qa/img34/v034_200node_tm2cmt1/cpu.png | Bin .../qa/img34/v034_200node_tm2cmt1/memory.png | Bin .../v034_200node_tm2cmt1/mempool_size.png | Bin .../qa/img34/v034_200node_tm2cmt1/peers.png | Bin .../qa/img34/v034_200node_tm2cmt1/rounds.png | Bin .../total_txs_rate_regular.png | Bin .../qa/img34/v034_latency_throughput.png | Bin .../qa/img34/v034_r200c2_heights.png | Bin .../qa/img34/v034_r200c2_load-runner.png | Bin .../qa/img34/v034_r200c2_load1.png | Bin .../qa/img34/v034_r200c2_mempool_size.png | Bin .../qa/img34/v034_r200c2_mempool_size_avg.png | Bin .../qa/img34/v034_r200c2_peers.png | Bin .../qa/img34/v034_r200c2_rounds.png | Bin .../qa/img34/v034_r200c2_rss.png | Bin .../qa/img34/v034_r200c2_rss_avg.png | Bin .../qa/img34/v034_r200c2_total-txs.png | Bin .../qa/img34/v034_report_tabbed.txt | 0 .../qa/img34/v034_rotating_heights.png | Bin .../qa/img34/v034_rotating_heights_ephe.png | Bin .../qa/img34/v034_rotating_latencies.png | Bin .../qa/img34/v034_rotating_latencies_uniq.png | Bin .../qa/img34/v034_rotating_load1.png | Bin .../qa/img34/v034_rotating_peers.png | Bin .../qa/img34/v034_rotating_rss_avg.png | Bin .../qa/img34/v034_rotating_total-txs.png | Bin .../img37/200nodes_cmt037/all_experiments.png | Bin .../200nodes_cmt037/avg_mempool_size.png | Bin .../qa/img37/200nodes_cmt037/block_rate.png | Bin .../qa/img37/200nodes_cmt037/cpu.png | Bin ...e_75cb89a8-f876-4698-82f3-8aaab0b361af.png | Bin .../qa/img37/200nodes_cmt037/memory.png | Bin .../qa/img37/200nodes_cmt037/mempool_size.png | Bin .../qa/img37/200nodes_cmt037/peers.png | Bin .../qa/img37/200nodes_cmt037/rounds.png | Bin .../img37/200nodes_cmt037/total_txs_rate.png | Bin .../img37/200nodes_tm037/avg_mempool_size.png | Bin .../200nodes_tm037/block_rate_regular.png | Bin .../qa/img37/200nodes_tm037/cpu.png | Bin .../qa/img37/200nodes_tm037/memory.png | Bin .../qa/img37/200nodes_tm037/mempool_size.png | Bin .../qa/img37/200nodes_tm037/peers.png | Bin .../qa/img37/200nodes_tm037/rounds.png | Bin .../200nodes_tm037/total_txs_rate_regular.png | Bin .../200nodes_tm037/v037_200node_latencies.png | Bin .../v037_latency_throughput.png | Bin .../200nodes_tm037/v037_r200c2_heights.png | Bin .../200nodes_tm037/v037_r200c2_load1.png | Bin .../v037_r200c2_mempool_size.png | Bin .../v037_r200c2_mempool_size_avg.png | Bin .../200nodes_tm037/v037_r200c2_peers.png | Bin .../200nodes_tm037/v037_r200c2_rounds.png | Bin .../img37/200nodes_tm037/v037_r200c2_rss.png | Bin .../200nodes_tm037/v037_r200c2_rss_avg.png | Bin .../200nodes_tm037/v037_r200c2_total-txs.png | Bin .../200nodes_tm037/v037_report_tabbed.txt | 0 .../200nodes_tm037/v037_rotating_heights.png | Bin .../v037_rotating_heights_ephe.png | Bin .../v037_rotating_latencies.png | Bin .../200nodes_tm037/v037_rotating_load1.png | Bin .../200nodes_tm037/v037_rotating_peers.png | Bin .../200nodes_tm037/v037_rotating_rss_avg.png | Bin .../v037_rotating_total-txs.png | Bin .../qa/img37/rotating/rotating_avg_memory.png | Bin .../qa/img37/rotating/rotating_block_rate.png | Bin .../qa/img37/rotating/rotating_cpu.png | Bin .../img37/rotating/rotating_eph_heights.png | Bin .../qa/img37/rotating/rotating_peers.png | Bin .../qa/img37/rotating/rotating_txs_rate.png | Bin .../qa/img38/200nodes/avg_mempool_size.png | Bin .../qa/img38/200nodes/block_rate.png | Bin .../qa/img38/200nodes/c1r400.png | Bin .../qa/img38/200nodes/cpu.png | Bin ...e_de676ecf-038e-443f-a26a-27915f29e312.png | Bin .../qa/img38/200nodes/memory.png | Bin .../qa/img38/200nodes/mempool_size.png | Bin .../qa/img38/200nodes/peers.png | Bin .../qa/img38/200nodes/rounds.png | Bin .../qa/img38/200nodes/total_txs_rate.png | Bin .../qa/img38/200nodes/v038_report_tabbed.txt | 0 .../qa/img38/rotating/rotating_avg_memory.png | Bin .../qa/img38/rotating/rotating_block_rate.png | Bin .../qa/img38/rotating/rotating_cpu.png | Bin .../img38/rotating/rotating_eph_heights.png | Bin .../qa/img38/rotating/rotating_latencies.png | Bin .../qa/img38/rotating/rotating_peers.png | Bin .../qa/img38/rotating/rotating_txs_rate.png | Bin .../img38/voteExtensions/02k_1_block_rate.png | Bin .../voteExtensions/02k_1_total_txs_rate.png | Bin .../qa/img38/voteExtensions/02k_avg_cpu.png | Bin .../img38/voteExtensions/02k_avg_memory.png | Bin .../voteExtensions/02k_avg_mempool_size.png | Bin .../img38/voteExtensions/02k_block_rate.png | Bin .../qa/img38/voteExtensions/02k_rounds.png | Bin .../voteExtensions/02k_total_txs_rate.png | Bin .../img38/voteExtensions/04k_1_block_rate.png | Bin .../voteExtensions/04k_1_total_txs_rate.png | Bin .../qa/img38/voteExtensions/04k_avg_cpu.png | Bin .../img38/voteExtensions/04k_avg_memory.png | Bin .../voteExtensions/04k_avg_mempool_size.png | Bin .../img38/voteExtensions/04k_block_rate.png | Bin .../qa/img38/voteExtensions/04k_rounds.png | Bin .../voteExtensions/04k_total_txs_rate.png | Bin .../voteExtensions/08k_1_avg_mempool_size.png | Bin .../img38/voteExtensions/08k_1_block_rate.png | Bin .../qa/img38/voteExtensions/08k_1_rounds.png | Bin .../voteExtensions/08k_1_total_txs_rate.png | Bin .../qa/img38/voteExtensions/08k_avg_cpu.png | Bin .../img38/voteExtensions/08k_avg_memory.png | Bin .../voteExtensions/08k_avg_mempool_size.png | Bin .../qa/img38/voteExtensions/08k_rounds.png | Bin .../voteExtensions/08k_total_txs_rate.png | Bin .../voteExtensions/16k_1_avg_mempool_size.png | Bin .../img38/voteExtensions/16k_1_block_rate.png | Bin .../qa/img38/voteExtensions/16k_1_rounds.png | Bin .../voteExtensions/16k_1_total_txs_rate.png | Bin .../qa/img38/voteExtensions/16k_avg_cpu.png | Bin .../img38/voteExtensions/16k_avg_memory.png | Bin .../voteExtensions/16k_avg_mempool_size.png | Bin .../img38/voteExtensions/16k_block_rate.png | Bin .../qa/img38/voteExtensions/16k_rounds.png | Bin .../voteExtensions/16k_total_txs_rate.png | Bin .../voteExtensions/32k_1_avg_mempool_size.png | Bin .../img38/voteExtensions/32k_1_block_rate.png | Bin .../qa/img38/voteExtensions/32k_1_rounds.png | Bin .../voteExtensions/32k_1_total_txs_rate.png | Bin .../qa/img38/voteExtensions/32k_avg_cpu.png | Bin .../img38/voteExtensions/32k_avg_memory.png | Bin .../voteExtensions/32k_avg_mempool_size.png | Bin .../img38/voteExtensions/32k_block_rate.png | Bin .../qa/img38/voteExtensions/32k_rounds.png | Bin .../voteExtensions/32k_total_txs_rate.png | Bin .../qa/img38/voteExtensions/8k_block_rate.png | Bin .../img38/voteExtensions/all_c1r400_16k.png | Bin .../qa/img38/voteExtensions/all_c1r400_2k.png | Bin .../img38/voteExtensions/all_c1r400_32k.png | Bin .../qa/img38/voteExtensions/all_c1r400_4k.png | Bin .../img38/voteExtensions/all_c1r400_64k.png | Bin .../qa/img38/voteExtensions/all_c1r400_8k.png | Bin .../voteExtensions/all_c1r400_baseline.png | Bin .../voteExtensions/all_experiments_16k.png | Bin .../voteExtensions/all_experiments_2k.png | Bin .../voteExtensions/all_experiments_32k.png | Bin .../voteExtensions/all_experiments_4k.png | Bin .../voteExtensions/all_experiments_64k.png | Bin .../voteExtensions/all_experiments_8k.png | Bin .../all_experiments_baseline.png | Bin .../baseline_1_avg_mempool_size.png | Bin .../voteExtensions/baseline_1_block_rate.png | Bin .../voteExtensions/baseline_1_rounds.png | Bin .../baseline_1_total_txs_rate.png | Bin .../img38/voteExtensions/baseline_avg_cpu.png | Bin .../voteExtensions/baseline_avg_memory.png | Bin .../baseline_avg_mempool_size.png | Bin .../voteExtensions/baseline_block_rate.png | Bin .../img38/voteExtensions/baseline_rounds.png | Bin .../baseline_total_txs_rate.png | Bin docs/{ => references}/qa/method.md | 22 +- docs/{ => references}/rfc/README.md | 20 +- .../rfc-103-optimization-comparison.png | Bin .../rfc/rfc-100-abci-vote-extension-propag.md | 0 .../rfc/rfc-101-p2p-bad-peers-checktx.md | 258 +++++++++--------- .../rfc/rfc-102-rust-gen-builders.md | 0 .../rfc-103-incoming-txs-when-catching-up.md | 10 +- .../rfc/rfc-104-actor-model.md | 0 .../rfc/rfc-105-non-det-process-proposal.md | 0 .../rfc/rfc-106-separate-stateful-methods.md | 0 .../rfc/rfc-107-event-observer.md | 2 +- docs/{ => references}/rfc/rfc-template.md | 0 docs/references/rfc/tendermint-core/README.md | 42 +++ .../rfc/tendermint-core/images/abci++.png | Bin .../rfc/tendermint-core/images/abci.png | Bin .../images/node-dependency-tree.svg | 0 .../images/receive-rate-all.png | Bin .../tendermint-core/images/send-rate-all.png | Bin .../images/top-3-percent-receive.png | Bin .../images/top-3-percent-send.png | Bin .../tendermint-core/rfc-000-p2p-roadmap.rst | 0 .../rfc-001-storage-engine.rst | 0 .../tendermint-core/rfc-002-ipc-ecosystem.md | 0 .../rfc-003-performance-questions.md | 0 .../tendermint-core/rfc-004-e2e-framework.rst | 0 .../tendermint-core/rfc-005-event-system.rst | 0 .../rfc-006-event-subscription.md | 4 +- .../rfc-007-deterministic-proto-bytes.md | 0 .../tendermint-core/rfc-008-do-not-panic.md | 0 .../rfc-009-consensus-parameter-upgrades.md | 0 .../rfc-010-p2p-light-client.rst | 0 .../rfc/tendermint-core/rfc-011-delete-gas.md | 0 .../rfc-012-custom-indexing.md | 0 .../rfc/tendermint-core/rfc-013-abci++.md | 0 .../rfc-014-semantic-versioning.md | 0 .../rfc-015-abci++-tx-mutation.md | 0 .../rfc-016-node-architecture.md | 4 +- .../rfc-017-abci++-vote-extension-propag.md | 0 .../rfc-018-bls-agg-exploration.md | 0 .../tendermint-core/rfc-019-config-version.md | 0 .../rfc-020-onboarding-projects.rst | 0 .../rfc-021-socket-protocol.md | 0 .../rfc-023-semi-permanent-testnet.md | 0 .../rfc-024-block-structure-consolidation.md | 0 .../rfc-025-support-app-side-mempool.md | 0 .../rfc-026-p2p-bad-peers-checktx.md | 0 .../rfc-027-p2p-message-bandwidth-report.md | 20 +- docs/rfc/tendermint-core/README.md | 42 --- docs/tutorials/README.md | 7 +- spec/abci/abci++_app_requirements.md | 56 ++-- spec/abci/abci++_comet_expected_behavior.md | 30 +- 379 files changed, 653 insertions(+), 577 deletions(-) delete mode 100644 docs/architecture/tendermint-core/README.md create mode 100644 docs/references/README.md rename docs/{ => references}/architecture/README.md (67%) rename docs/{ => references}/architecture/adr-100-data-companion-push-api.md (99%) rename docs/{ => references}/architecture/adr-101-data-companion-pull-api.md (97%) rename docs/{ => references}/architecture/adr-103-proto-versioning.md (100%) rename docs/{ => references}/architecture/adr-104-out-of-band-state-sync.md (91%) rename docs/{ => references}/architecture/adr-105-refactor-mempool-senders.md (100%) rename docs/{ => references}/architecture/adr-107-betaize-proto-versions.md (100%) rename docs/{ => references}/architecture/adr-108-e2e-abci++.md (82%) rename docs/{ => references}/architecture/adr-109-reduce-go-api-surface.md (99%) rename docs/{ => references}/architecture/adr-110-remote-mempool.md (99%) rename docs/{ => references}/architecture/adr-111-nop-mempool.md (100%) rename docs/{ => references}/architecture/adr-template.md (100%) create mode 100644 docs/references/architecture/tendermint-core/README.md rename docs/{ => references}/architecture/tendermint-core/adr-001-logging.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-002-event-subscription.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-003-abci-app-rpc.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-004-historical-validators.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-005-consensus-params.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-006-trust-metric.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-007-trust-metric-usage.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-008-priv-validator.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-009-ABCI-design.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-010-crypto-changes.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-011-monitoring.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-012-peer-transport.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-013-symmetric-crypto.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-014-secp-malleability.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-015-crypto-encoding.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-016-protocol-versions.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-017-chain-versions.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-018-ABCI-Validators.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-019-multisigs.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-020-block-size.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-021-abci-events.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-022-abci-errors.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-023-ABCI-propose-tx.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-024-sign-bytes.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-025-commit.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-026-general-merkle-proof.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-029-check-tx-consensus.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-030-consensus-refactor.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-033-pubsub.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-034-priv-validator-file-structure.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-035-documentation.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-036-empty-blocks-abci.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-037-deliver-block.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-038-non-zero-start-height.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-039-peer-behaviour.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-040-blockchain-reactor-refactor.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-041-proposer-selection-via-abci.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-042-state-sync.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-043-blockchain-riri-org.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-044-lite-client-with-weak-subjectivity.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-045-abci-evidence.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-046-light-client-implementation.md (99%) rename docs/{ => references}/architecture/tendermint-core/adr-047-handling-evidence-from-light-client.md (99%) rename docs/{ => references}/architecture/tendermint-core/adr-050-improved-trusted-peering.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-051-double-signing-risk-reduction.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-052-tendermint-mode.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-053-state-sync-prototype.md (98%) rename docs/{ => references}/architecture/tendermint-core/adr-054-crypto-encoding-2.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-055-protobuf-design.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-056-light-client-amnesia-attacks.md (99%) rename docs/{ => references}/architecture/tendermint-core/adr-057-RPC.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-058-event-hashing.md (99%) rename docs/{ => references}/architecture/tendermint-core/adr-059-evidence-composition-and-lifecycle.md (99%) rename docs/{ => references}/architecture/tendermint-core/adr-060-go-api-stability.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-061-p2p-refactor-scope.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-062-p2p-architecture.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-063-privval-grpc.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-064-batch-verification.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-065-custom-event-indexing.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-066-e2e-testing.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-067-mempool-refactor.md (99%) rename docs/{ => references}/architecture/tendermint-core/adr-068-reverse-sync.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-069-flexible-node-initialization.md (97%) rename docs/{ => references}/architecture/tendermint-core/adr-071-proposer-based-timestamps.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-072-request-for-comments.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-073-libp2p.md (99%) rename docs/{ => references}/architecture/tendermint-core/adr-074-timeout-params.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-075-rpc-subscription.md (99%) rename docs/{ => references}/architecture/tendermint-core/adr-076-combine-spec-repo.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-077-block-retention.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-078-nonzero-genesis.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-079-ed25519-verification.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-080-reverse-sync.md (100%) rename docs/{ => references}/architecture/tendermint-core/adr-081-protobuf-mgmt.md (100%) rename docs/{ => references}/architecture/tendermint-core/img/adr-046-fig1.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/adr-062-architecture.svg (100%) rename docs/{ => references}/architecture/tendermint-core/img/adr-075-log-after.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/adr-075-log-before.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/bc-reactor-refactor.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/bc-reactor.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/bifurcation-point.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/block-retention.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/blockchain-reactor-v1.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/blockchain-reactor-v2.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/blockchain-v2-channels.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/consensus_blockchain.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/evidence_lifecycle.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/formula1.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/formula2.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/light-client-detector.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/mempool-v0.jpeg (100%) rename docs/{ => references}/architecture/tendermint-core/img/pbts-message.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/state-sync.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/tags1.png (100%) rename docs/{ => references}/architecture/tendermint-core/img/tm-amnesia-attack.png (100%) rename docs/{ => references}/qa/CometBFT-QA-34.md (100%) rename docs/{ => references}/qa/CometBFT-QA-37.md (100%) rename docs/{ => references}/qa/CometBFT-QA-38.md (99%) rename docs/{ => references}/qa/README.md (94%) rename docs/{ => references}/qa/TMCore-QA-34.md (100%) rename docs/{ => references}/qa/TMCore-QA-37.md (100%) rename docs/{ => references}/qa/img34/baseline/avg_cpu.png (100%) rename docs/{ => references}/qa/img34/baseline/avg_memory.png (100%) rename docs/{ => references}/qa/img34/baseline/avg_mempool_size.png (100%) rename docs/{ => references}/qa/img34/baseline/block_rate_regular.png (100%) rename docs/{ => references}/qa/img34/baseline/cpu.png (100%) rename docs/{ => references}/qa/img34/baseline/memory.png (100%) rename docs/{ => references}/qa/img34/baseline/mempool_size.png (100%) rename docs/{ => references}/qa/img34/baseline/peers.png (100%) rename docs/{ => references}/qa/img34/baseline/rounds.png (100%) rename docs/{ => references}/qa/img34/baseline/total_txs_rate_regular.png (100%) rename docs/{ => references}/qa/img34/cmt1tm1/all_experiments.png (100%) rename docs/{ => references}/qa/img34/cmt1tm1/avg_cpu.png (100%) rename docs/{ => references}/qa/img34/cmt1tm1/avg_memory.png (100%) rename docs/{ => references}/qa/img34/cmt1tm1/avg_mempool_size.png (100%) rename docs/{ => references}/qa/img34/cmt1tm1/block_rate_regular.png (100%) rename docs/{ => references}/qa/img34/cmt1tm1/cpu.png (100%) rename docs/{ => references}/qa/img34/cmt1tm1/memory.png (100%) rename docs/{ => references}/qa/img34/cmt1tm1/mempool_size.png (100%) rename docs/{ => references}/qa/img34/cmt1tm1/peers.png (100%) rename docs/{ => references}/qa/img34/cmt1tm1/rounds.png (100%) rename docs/{ => references}/qa/img34/cmt1tm1/total_txs_rate_regular.png (100%) rename docs/{ => references}/qa/img34/cmt2tm1/all_experiments.png (100%) rename docs/{ => references}/qa/img34/cmt2tm1/avg_cpu.png (100%) rename docs/{ => references}/qa/img34/cmt2tm1/avg_memory.png (100%) rename docs/{ => references}/qa/img34/cmt2tm1/avg_mempool_size.png (100%) rename docs/{ => references}/qa/img34/cmt2tm1/block_rate_regular.png (100%) rename docs/{ => references}/qa/img34/cmt2tm1/cpu.png (100%) rename docs/{ => references}/qa/img34/cmt2tm1/memory.png (100%) rename docs/{ => references}/qa/img34/cmt2tm1/mempool_size.png (100%) rename docs/{ => references}/qa/img34/cmt2tm1/peers.png (100%) rename docs/{ => references}/qa/img34/cmt2tm1/rounds.png (100%) rename docs/{ => references}/qa/img34/cmt2tm1/total_txs_rate_regular.png (100%) rename docs/{ => references}/qa/img34/homogeneous/all_experiments.png (100%) rename docs/{ => references}/qa/img34/homogeneous/avg_cpu.png (100%) rename docs/{ => references}/qa/img34/homogeneous/avg_memory.png (100%) rename docs/{ => references}/qa/img34/homogeneous/avg_mempool_size.png (100%) rename docs/{ => references}/qa/img34/homogeneous/block_rate_regular.png (100%) rename docs/{ => references}/qa/img34/homogeneous/cpu.png (100%) rename docs/{ => references}/qa/img34/homogeneous/memory.png (100%) rename docs/{ => references}/qa/img34/homogeneous/mempool_size.png (100%) rename docs/{ => references}/qa/img34/homogeneous/peers.png (100%) rename docs/{ => references}/qa/img34/homogeneous/rounds.png (100%) rename docs/{ => references}/qa/img34/homogeneous/total_txs_rate_regular.png (100%) rename docs/{ => references}/qa/img34/v034_200node_latencies.png (100%) rename docs/{ => references}/qa/img34/v034_200node_latencies_zoomed.png (100%) rename docs/{ => references}/qa/img34/v034_200node_tm2cmt1/all_experiments.png (100%) rename docs/{ => references}/qa/img34/v034_200node_tm2cmt1/avg_cpu.png (100%) rename docs/{ => references}/qa/img34/v034_200node_tm2cmt1/avg_memory.png (100%) rename docs/{ => references}/qa/img34/v034_200node_tm2cmt1/avg_mempool_size.png (100%) rename docs/{ => references}/qa/img34/v034_200node_tm2cmt1/block_rate_regular.png (100%) rename docs/{ => references}/qa/img34/v034_200node_tm2cmt1/c2r200_merged.png (100%) rename docs/{ => references}/qa/img34/v034_200node_tm2cmt1/cpu.png (100%) rename docs/{ => references}/qa/img34/v034_200node_tm2cmt1/memory.png (100%) rename docs/{ => references}/qa/img34/v034_200node_tm2cmt1/mempool_size.png (100%) rename docs/{ => references}/qa/img34/v034_200node_tm2cmt1/peers.png (100%) rename docs/{ => references}/qa/img34/v034_200node_tm2cmt1/rounds.png (100%) rename docs/{ => references}/qa/img34/v034_200node_tm2cmt1/total_txs_rate_regular.png (100%) rename docs/{ => references}/qa/img34/v034_latency_throughput.png (100%) rename docs/{ => references}/qa/img34/v034_r200c2_heights.png (100%) rename docs/{ => references}/qa/img34/v034_r200c2_load-runner.png (100%) rename docs/{ => references}/qa/img34/v034_r200c2_load1.png (100%) rename docs/{ => references}/qa/img34/v034_r200c2_mempool_size.png (100%) rename docs/{ => references}/qa/img34/v034_r200c2_mempool_size_avg.png (100%) rename docs/{ => references}/qa/img34/v034_r200c2_peers.png (100%) rename docs/{ => references}/qa/img34/v034_r200c2_rounds.png (100%) rename docs/{ => references}/qa/img34/v034_r200c2_rss.png (100%) rename docs/{ => references}/qa/img34/v034_r200c2_rss_avg.png (100%) rename docs/{ => references}/qa/img34/v034_r200c2_total-txs.png (100%) rename docs/{ => references}/qa/img34/v034_report_tabbed.txt (100%) rename docs/{ => references}/qa/img34/v034_rotating_heights.png (100%) rename docs/{ => references}/qa/img34/v034_rotating_heights_ephe.png (100%) rename docs/{ => references}/qa/img34/v034_rotating_latencies.png (100%) rename docs/{ => references}/qa/img34/v034_rotating_latencies_uniq.png (100%) rename docs/{ => references}/qa/img34/v034_rotating_load1.png (100%) rename docs/{ => references}/qa/img34/v034_rotating_peers.png (100%) rename docs/{ => references}/qa/img34/v034_rotating_rss_avg.png (100%) rename docs/{ => references}/qa/img34/v034_rotating_total-txs.png (100%) rename docs/{ => references}/qa/img37/200nodes_cmt037/all_experiments.png (100%) rename docs/{ => references}/qa/img37/200nodes_cmt037/avg_mempool_size.png (100%) rename docs/{ => references}/qa/img37/200nodes_cmt037/block_rate.png (100%) rename docs/{ => references}/qa/img37/200nodes_cmt037/cpu.png (100%) rename docs/{ => references}/qa/img37/200nodes_cmt037/e_75cb89a8-f876-4698-82f3-8aaab0b361af.png (100%) rename docs/{ => references}/qa/img37/200nodes_cmt037/memory.png (100%) rename docs/{ => references}/qa/img37/200nodes_cmt037/mempool_size.png (100%) rename docs/{ => references}/qa/img37/200nodes_cmt037/peers.png (100%) rename docs/{ => references}/qa/img37/200nodes_cmt037/rounds.png (100%) rename docs/{ => references}/qa/img37/200nodes_cmt037/total_txs_rate.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/avg_mempool_size.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/block_rate_regular.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/cpu.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/memory.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/mempool_size.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/peers.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/rounds.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/total_txs_rate_regular.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_200node_latencies.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_latency_throughput.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_r200c2_heights.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_r200c2_load1.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_r200c2_mempool_size.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_r200c2_mempool_size_avg.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_r200c2_peers.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_r200c2_rounds.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_r200c2_rss.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_r200c2_rss_avg.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_r200c2_total-txs.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_report_tabbed.txt (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_rotating_heights.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_rotating_heights_ephe.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_rotating_latencies.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_rotating_load1.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_rotating_peers.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_rotating_rss_avg.png (100%) rename docs/{ => references}/qa/img37/200nodes_tm037/v037_rotating_total-txs.png (100%) rename docs/{ => references}/qa/img37/rotating/rotating_avg_memory.png (100%) rename docs/{ => references}/qa/img37/rotating/rotating_block_rate.png (100%) rename docs/{ => references}/qa/img37/rotating/rotating_cpu.png (100%) rename docs/{ => references}/qa/img37/rotating/rotating_eph_heights.png (100%) rename docs/{ => references}/qa/img37/rotating/rotating_peers.png (100%) rename docs/{ => references}/qa/img37/rotating/rotating_txs_rate.png (100%) rename docs/{ => references}/qa/img38/200nodes/avg_mempool_size.png (100%) rename docs/{ => references}/qa/img38/200nodes/block_rate.png (100%) rename docs/{ => references}/qa/img38/200nodes/c1r400.png (100%) rename docs/{ => references}/qa/img38/200nodes/cpu.png (100%) rename docs/{ => references}/qa/img38/200nodes/e_de676ecf-038e-443f-a26a-27915f29e312.png (100%) rename docs/{ => references}/qa/img38/200nodes/memory.png (100%) rename docs/{ => references}/qa/img38/200nodes/mempool_size.png (100%) rename docs/{ => references}/qa/img38/200nodes/peers.png (100%) rename docs/{ => references}/qa/img38/200nodes/rounds.png (100%) rename docs/{ => references}/qa/img38/200nodes/total_txs_rate.png (100%) rename docs/{ => references}/qa/img38/200nodes/v038_report_tabbed.txt (100%) rename docs/{ => references}/qa/img38/rotating/rotating_avg_memory.png (100%) rename docs/{ => references}/qa/img38/rotating/rotating_block_rate.png (100%) rename docs/{ => references}/qa/img38/rotating/rotating_cpu.png (100%) rename docs/{ => references}/qa/img38/rotating/rotating_eph_heights.png (100%) rename docs/{ => references}/qa/img38/rotating/rotating_latencies.png (100%) rename docs/{ => references}/qa/img38/rotating/rotating_peers.png (100%) rename docs/{ => references}/qa/img38/rotating/rotating_txs_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/02k_1_block_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/02k_1_total_txs_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/02k_avg_cpu.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/02k_avg_memory.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/02k_avg_mempool_size.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/02k_block_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/02k_rounds.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/02k_total_txs_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/04k_1_block_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/04k_1_total_txs_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/04k_avg_cpu.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/04k_avg_memory.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/04k_avg_mempool_size.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/04k_block_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/04k_rounds.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/04k_total_txs_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/08k_1_avg_mempool_size.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/08k_1_block_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/08k_1_rounds.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/08k_1_total_txs_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/08k_avg_cpu.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/08k_avg_memory.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/08k_avg_mempool_size.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/08k_rounds.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/08k_total_txs_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/16k_1_avg_mempool_size.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/16k_1_block_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/16k_1_rounds.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/16k_1_total_txs_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/16k_avg_cpu.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/16k_avg_memory.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/16k_avg_mempool_size.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/16k_block_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/16k_rounds.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/16k_total_txs_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/32k_1_avg_mempool_size.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/32k_1_block_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/32k_1_rounds.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/32k_1_total_txs_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/32k_avg_cpu.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/32k_avg_memory.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/32k_avg_mempool_size.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/32k_block_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/32k_rounds.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/32k_total_txs_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/8k_block_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/all_c1r400_16k.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/all_c1r400_2k.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/all_c1r400_32k.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/all_c1r400_4k.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/all_c1r400_64k.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/all_c1r400_8k.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/all_c1r400_baseline.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/all_experiments_16k.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/all_experiments_2k.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/all_experiments_32k.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/all_experiments_4k.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/all_experiments_64k.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/all_experiments_8k.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/all_experiments_baseline.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/baseline_1_avg_mempool_size.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/baseline_1_block_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/baseline_1_rounds.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/baseline_1_total_txs_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/baseline_avg_cpu.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/baseline_avg_memory.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/baseline_avg_mempool_size.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/baseline_block_rate.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/baseline_rounds.png (100%) rename docs/{ => references}/qa/img38/voteExtensions/baseline_total_txs_rate.png (100%) rename docs/{ => references}/qa/method.md (96%) rename docs/{ => references}/rfc/README.md (68%) rename docs/{ => references}/rfc/images/rfc-103-optimization-comparison.png (100%) rename docs/{ => references}/rfc/rfc-100-abci-vote-extension-propag.md (100%) rename docs/{ => references}/rfc/rfc-101-p2p-bad-peers-checktx.md (85%) rename docs/{ => references}/rfc/rfc-102-rust-gen-builders.md (100%) rename docs/{ => references}/rfc/rfc-103-incoming-txs-when-catching-up.md (97%) rename docs/{ => references}/rfc/rfc-104-actor-model.md (100%) rename docs/{ => references}/rfc/rfc-105-non-det-process-proposal.md (100%) rename docs/{ => references}/rfc/rfc-106-separate-stateful-methods.md (100%) rename docs/{ => references}/rfc/rfc-107-event-observer.md (99%) rename docs/{ => references}/rfc/rfc-template.md (100%) create mode 100644 docs/references/rfc/tendermint-core/README.md rename docs/{ => references}/rfc/tendermint-core/images/abci++.png (100%) rename docs/{ => references}/rfc/tendermint-core/images/abci.png (100%) rename docs/{ => references}/rfc/tendermint-core/images/node-dependency-tree.svg (100%) rename docs/{ => references}/rfc/tendermint-core/images/receive-rate-all.png (100%) rename docs/{ => references}/rfc/tendermint-core/images/send-rate-all.png (100%) rename docs/{ => references}/rfc/tendermint-core/images/top-3-percent-receive.png (100%) rename docs/{ => references}/rfc/tendermint-core/images/top-3-percent-send.png (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-000-p2p-roadmap.rst (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-001-storage-engine.rst (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-002-ipc-ecosystem.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-003-performance-questions.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-004-e2e-framework.rst (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-005-event-system.rst (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-006-event-subscription.md (99%) rename docs/{ => references}/rfc/tendermint-core/rfc-007-deterministic-proto-bytes.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-008-do-not-panic.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-009-consensus-parameter-upgrades.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-010-p2p-light-client.rst (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-011-delete-gas.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-012-custom-indexing.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-013-abci++.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-014-semantic-versioning.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-015-abci++-tx-mutation.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-016-node-architecture.md (95%) rename docs/{ => references}/rfc/tendermint-core/rfc-017-abci++-vote-extension-propag.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-018-bls-agg-exploration.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-019-config-version.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-020-onboarding-projects.rst (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-021-socket-protocol.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-023-semi-permanent-testnet.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-024-block-structure-consolidation.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-025-support-app-side-mempool.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-026-p2p-bad-peers-checktx.md (100%) rename docs/{ => references}/rfc/tendermint-core/rfc-027-p2p-message-bandwidth-report.md (98%) delete mode 100644 docs/rfc/tendermint-core/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 392b26168a3..9004e8da2a3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,16 +20,16 @@ team, including: transaction dissemination mechanism, for example a standalone mempool-like process that can be scaled independently of the consensus engine/application. This requires application developers to implement their own gossip/networking - mechanisms. See [ADR 111](./docs/architecture/adr-111-nop-mempool.md) for + mechanisms. See [ADR 111](docs/references/architecture/adr-111-nop-mempool.md) for details. 4. The first officially supported release of the [data companion - API](./docs/architecture/adr-101-data-companion-pull-api.md). + API](docs/references/architecture/adr-101-data-companion-pull-api.md). 5. Versioning of both the Protobuf definitions _and_ RPC. By versioning our APIs, we aim to provide a level of commitment to API stability while simultaneously affording ourselves the ability to roll out substantial changes in non-breaking releases of CometBFT. See [ADR - 103](./docs/architecture/adr-103-proto-versioning.md) and [ADR - 107](./docs/architecture/adr-107-betaize-proto-versions.md). + 103](docs/references/architecture/adr-103-proto-versioning.md) and [ADR + 107](docs/references/architecture/adr-107-betaize-proto-versions.md). 6. Moving many Go packages that are currently publicly accessible into the `internal` directory such that the team can roll out substantial changes in future without needing to worry about causing breakages in users' codebases. @@ -37,7 +37,7 @@ team, including: hampered the team's ability to roll out impactful new changes to users, as previously such changes required a new breaking release (which currently takes 6 to 12 months to reach production use for many users). See [ADR - 109](./docs/architecture/adr-109-reduce-go-api-surface.md) for more details. + 109](docs/references/architecture/adr-109-reduce-go-api-surface.md) for more details. None of these changes are state machine-breaking for CometBFT-based networks, but could be breaking for some users who depend on the Protobuf definitions type @@ -76,7 +76,7 @@ the stability guarantees we provide for pre-releases. and corresponding consensus file replay code, such as `consensus.RunReplayFile`, and `consensus.State.ReplayFile` ([\#1170](https://github.com/cometbft/cometbft/pull/1170)) -- `[comet]` Version variables, in `version/version.go`, have been renamed to reflect the CometBFT rebranding. +- `[comet]` Version variables, in `version/version.go`, have been renamed to reflect the CometBFT rebranding. ([cometbft/cometbft\#1621](https://github.com/cometbft/cometbft/pull/1621)) - `[consensus]` Move to `internal` ([\#1485](https://github.com/cometbft/cometbft/pull/1485)) @@ -132,7 +132,7 @@ the stability guarantees we provide for pre-releases. - `[node]` Change the signature of `GenesisDocProvider` to return the checksum of JSON content alongside the parsed genesis data ([\#1287](https://github.com/cometbft/cometbft/issues/1287)). -- `[node]` Go-API breaking: Change the signature of `LoadStateFromDBOrGenesisDocProvider` +- `[node]` Go-API breaking: Change the signature of `LoadStateFromDBOrGenesisDocProvider` to accept an optional operator provided hash of the genesis file ([\#1324](https://github.com/cometbft/cometbft/pull/1324)). - `[proto]` Renamed the packages from `tendermint.*` to `cometbft.*` @@ -140,7 +140,7 @@ the stability guarantees we provide for pre-releases. released in 0.34.x, 0.37.x, 0.38.x, and 1.0.x versions. Prior to the 1.0 release, the versioned packages are suffixed with `.v1beta1`, `.v1beta2`, and so on; all definitions describing the protocols - as per the 1.0.0 release are in packages suffixed with `.v1`. + as per the 1.0.0 release are in packages suffixed with `.v1`. Relocated generated Go code into a new `api` folder and changed the import paths accordingly. ([\#495](https://github.com/cometbft/cometbft/pull/495) @@ -228,10 +228,10 @@ the stability guarantees we provide for pre-releases. ``` - `[metrics]` Add metric for mempool size in bytes `SizeBytes`. ([\#1512](https://github.com/cometbft/cometbft/pull/1512)) -- `[metrics]` Add metrics to monitor pruning and current available data in stores: `PruningServiceBlockRetainHeight`, `PruningServiceBlockResultsRetainHeight`, `ApplicationBlockRetainHeight`, `BlockStoreBaseHeight`, `ABCIResultsBaseHeight`. +- `[metrics]` Add metrics to monitor pruning and current available data in stores: `PruningServiceBlockRetainHeight`, `PruningServiceBlockResultsRetainHeight`, `ApplicationBlockRetainHeight`, `BlockStoreBaseHeight`, `ABCIResultsBaseHeight`. ([\#1234](https://github.com/cometbft/cometbft/pull/1234)) - `[proto]` Add definitions and generated code for - [ADR-101](./docs/architecture/adr-101-data-companion-pull-api.md) + [ADR-101](docs/references/architecture/adr-101-data-companion-pull-api.md) `PruningService` in the `cometbft.services.pruning.v1` proto package ([\#1097](https://github.com/cometbft/cometbft/issues/1097)). - `[rpc/grpc]` Add privileged gRPC server and client facilities, in @@ -240,7 +240,7 @@ the stability guarantees we provide for pre-releases. without authentication and should never be exposed to public internet ([\#1097](https://github.com/cometbft/cometbft/issues/1097)). - `[rpc/grpc]` Add a pruning service adding on the privileged gRPC server API to - give an [ADR-101](./docs/architecture/adr-101-data-companion-pull-api.md) data + give an [ADR-101](docs/references/architecture/adr-101-data-companion-pull-api.md) data companion control over block data retained by the node. The `WithPruningService` option method in `server/privileged` is provided to configure the pruning service @@ -276,7 +276,7 @@ the stability guarantees we provide for pre-releases. - `[abci/client]` Add fully unsynchronized local client creator, which imposes no mutexes on the application, leaving all handling of concurrency up to the application ([\#1141](https://github.com/cometbft/cometbft/pull/1141)) -- `[cli/node]` The genesis hash provided with the `--genesis-hash` is now +- `[cli/node]` The genesis hash provided with the `--genesis-hash` is now forwarded to the node, instead of reading the file. ([\#1324](https://github.com/cometbft/cometbft/pull/1324)). - `[config]` Added `[storage.pruning]` and `[storage.pruning.data_companion]` @@ -307,7 +307,7 @@ the stability guarantees we provide for pre-releases. ([\#1584](https://github.com/cometbft/cometbft/pull/1584)) - `[config]` Add mempool parameters `experimental_max_gossip_connections_to_persistent_peers` and `experimental_max_gossip_connections_to_non_persistent_peers` for limiting the number of peers to - which the node gossip transactions. + which the node gossip transactions. ([\#1558](https://github.com/cometbft/cometbft/pull/1558)) ([\#1584](https://github.com/cometbft/cometbft/pull/1584)) - `[node]` On upgrade, after [\#1296](https://github.com/cometbft/cometbft/pull/1296), delete the genesis file existing in the DB. @@ -475,7 +475,7 @@ gossip. ([\#1584](https://github.com/cometbft/cometbft/pull/1584)) - `[config]` Add mempool parameters `experimental_max_gossip_connections_to_persistent_peers` and `experimental_max_gossip_connections_to_non_persistent_peers` for limiting the number of peers to - which the node gossip transactions. + which the node gossip transactions. ([\#1558](https://github.com/cometbft/cometbft/pull/1558)) ([\#1584](https://github.com/cometbft/cometbft/pull/1584)) @@ -513,7 +513,7 @@ gossip. ([\#1584](https://github.com/cometbft/cometbft/pull/1584)) - `[config]` Add mempool parameters `experimental_max_gossip_connections_to_persistent_peers` and `experimental_max_gossip_connections_to_non_persistent_peers` for limiting the number of peers to - which the node gossip transactions. + which the node gossip transactions. ([\#1558](https://github.com/cometbft/cometbft/pull/1558)) ([\#1584](https://github.com/cometbft/cometbft/pull/1584)) - `[node]` Close evidence.db OnStop ([cometbft/cometbft\#1210](https://github.com/cometbft/cometbft/pull/1210): @chillyvee) @@ -545,7 +545,7 @@ gossip. ([\#1584](https://github.com/cometbft/cometbft/pull/1584)) - `[config]` Add mempool parameters `experimental_max_gossip_connections_to_persistent_peers` and `experimental_max_gossip_connections_to_non_persistent_peers` for limiting the number of peers to - which the node gossip transactions. + which the node gossip transactions. ([\#1558](https://github.com/cometbft/cometbft/pull/1558)) ([\#1584](https://github.com/cometbft/cometbft/pull/1584)) - `[node]` Close evidence.db OnStop ([cometbft/cometbft\#1210](https://github.com/cometbft/cometbft/pull/1210): @chillyvee) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eeedc5708e1..6158c47003a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -126,7 +126,7 @@ problems and help structure conversations around trade-offs. When the problem is well understood but the solution leads to large/complex/risky structural changes to the code base, these changes should be proposed in the form of an [Architectural Decision Record -(ADR)](./docs/architecture/). The ADR will help build consensus on an overall +(ADR)](docs/references/architecture/). The ADR will help build consensus on an overall strategy to ensure the code base maintains coherence in the larger context. If you are not comfortable with writing an ADR, you can open a less-formal issue and the maintainers will help you turn it into an ADR. Sometimes the best way to diff --git a/README.md b/README.md index 5813bec08ea..c1b6188a533 100644 --- a/README.md +++ b/README.md @@ -85,8 +85,8 @@ Before contributing to the project, please take a look at the [contributing guidelines](CONTRIBUTING.md) and the [style guide](STYLE_GUIDE.md). You may also find it helpful to read the [specifications](./spec/README.md), and familiarize yourself with our [Architectural Decision Records -(ADRs)](./docs/architecture/README.md) and [Request For Comments -(RFCs)](./docs/rfc/README.md). +(ADRs)](docs/references/architecture/README.md) and [Request For Comments +(RFCs)](docs/references/rfc/README.md). ## Versioning diff --git a/UPGRADING.md b/UPGRADING.md index 9662aba5725..c325972ecc2 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -43,7 +43,7 @@ which were also removed. (See ### Go API -As per [ADR 109](./docs/architecture/adr-109-reduce-go-api-surface.md), the +As per [ADR 109](docs/references/architecture/adr-109-reduce-go-api-surface.md), the following packages that were publicly accessible in CometBFT v0.38 were moved into the `internal` directory: diff --git a/docs/architecture/tendermint-core/README.md b/docs/architecture/tendermint-core/README.md deleted file mode 100644 index d1d8c276f34..00000000000 --- a/docs/architecture/tendermint-core/README.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -order: 1 -parent: - order: false ---- - -# Tendermint Core Architecture Decision Records (ADR) - -Here we record all high-level architecture decisions in the Tendermint Core -project. All implemented ADRs in this list naturally affect CometBFT, since -CometBFT is a fork of Tendermint Core as of December 2022. - -This list is currently frozen and kept for reference purposes. To add new ADRs, -please do so for CometBFT [here](../). - -## Table of Contents - -### Implemented - -- [ADR-001: Logging](./adr-001-logging.md) -- [ADR-002: Event-Subscription](./adr-002-event-subscription.md) -- [ADR-003: ABCI-APP-RPC](./adr-003-abci-app-rpc.md) -- [ADR-004: Historical-Validators](./adr-004-historical-validators.md) -- [ADR-005: Consensus-Params](./adr-005-consensus-params.md) -- [ADR-008: Priv-Validator](./adr-008-priv-validator.md) -- [ADR-009: ABCI-Design](./adr-009-ABCI-design.md) -- [ADR-010: Crypto-Changes](./adr-010-crypto-changes.md) -- [ADR-011: Monitoring](./adr-011-monitoring.md) -- [ADR-014: Secp-Malleability](./adr-014-secp-malleability.md) -- [ADR-015: Crypto-Encoding](./adr-015-crypto-encoding.md) -- [ADR-016: Protocol-Versions](./adr-016-protocol-versions.md) -- [ADR-017: Chain-Versions](./adr-017-chain-versions.md) -- [ADR-018: ABCI-Validators](./adr-018-ABCI-Validators.md) -- [ADR-019: Multisigs](./adr-019-multisigs.md) -- [ADR-020: Block-Size](./adr-020-block-size.md) -- [ADR-021: ABCI-Events](./adr-021-abci-events.md) -- [ADR-025: Commit](./adr-025-commit.md) -- [ADR-026: General-Merkle-Proof](./adr-026-general-merkle-proof.md) -- [ADR-033: Pubsub](./adr-033-pubsub.md) -- [ADR-034: Priv-Validator-File-Structure](./adr-034-priv-validator-file-structure.md) -- [ADR-043: Blockchain-RiRi-Org](./adr-043-blockchain-riri-org.md) -- [ADR-044: Lite-Client-With-Weak-Subjectivity](./adr-044-lite-client-with-weak-subjectivity.md) -- [ADR-046: Light-Client-Implementation](./adr-046-light-client-implementation.md) -- [ADR-047: Handling-Evidence-From-Light-Client](./adr-047-handling-evidence-from-light-client.md) -- [ADR-051: Double-Signing-Risk-Reduction](./adr-051-double-signing-risk-reduction.md) -- [ADR-052: Tendermint-Mode](./adr-052-tendermint-mode.md) -- [ADR-053: State-Sync-Prototype](./adr-053-state-sync-prototype.md) -- [ADR-054: Crypto-Encoding-2](./adr-054-crypto-encoding-2.md) -- [ADR-055: Protobuf-Design](./adr-055-protobuf-design.md) -- [ADR-056: Light-Client-Amnesia-Attacks](./adr-056-light-client-amnesia-attacks.md) -- [ADR-059: Evidence-Composition-and-Lifecycle](./adr-059-evidence-composition-and-lifecycle.md) -- [ADR-065: Custom Event Indexing](./adr-065-custom-event-indexing.md) -- [ADR-066: E2E-Testing](./adr-066-e2e-testing.md) -- [ADR-072: Restore Requests for Comments](./adr-072-request-for-comments.md) -- [ADR-076: Combine Spec and Tendermint Repositories](./adr-076-combine-spec-repo.md) -- [ADR-077: Configurable Block Retention](./adr-077-block-retention.md) -- [ADR-078: Non-zero Genesis](./adr-078-nonzero-genesis.md) - -### Accepted - -- [ADR-006: Trust-Metric](./adr-006-trust-metric.md) -- [ADR-024: Sign-Bytes](./adr-024-sign-bytes.md) -- [ADR-039: Peer-Behaviour](./adr-039-peer-behaviour.md) -- [ADR-063: Privval-gRPC](./adr-063-privval-grpc.md) -- [ADR-067: Mempool Refactor](./adr-067-mempool-refactor.md) -- [ADR-071: Proposer-Based Timestamps](./adr-071-proposer-based-timestamps.md) -- [ADR-075: RPC Event Subscription Interface](./adr-075-rpc-subscription.md) -- [ADR-079: Ed25519 Verification](./adr-079-ed25519-verification.md) -- [ADR-081: Protocol Buffers Management](./adr-081-protobuf-mgmt.md) - -### Deprecated - -- [ADR-035: Documentation](./adr-035-documentation.md) - -### Rejected - -- [ADR-023: ABCI-Propose-tx](./adr-023-ABCI-propose-tx.md) -- [ADR-029: Check-Tx-Consensus](./adr-029-check-tx-consensus.md) -- [ADR-058: Event-Hashing](./adr-058-event-hashing.md) - -### Proposed - -- [ADR-007: Trust-Metric-Usage](./adr-007-trust-metric-usage.md) -- [ADR-012: Peer-Transport](./adr-012-peer-transport.md) -- [ADR-013: Symmetric-Crypto](./adr-013-symmetric-crypto.md) -- [ADR-022: ABCI-Errors](./adr-022-abci-errors.md) -- [ADR-030: Consensus-Refactor](./adr-030-consensus-refactor.md) -- [ADR-036: Empty Blocks via ABCI](./adr-036-empty-blocks-abci.md) -- [ADR-037: Deliver-Block](./adr-037-deliver-block.md) -- [ADR-038: Non-Zero-Start-Height](./adr-038-non-zero-start-height.md) -- [ADR-040: Blockchain Reactor Refactor](./adr-040-blockchain-reactor-refactor.md) -- [ADR-041: Proposer-Selection-via-ABCI](./adr-041-proposer-selection-via-abci.md) -- [ADR-042: State Sync Design](./adr-042-state-sync.md) -- [ADR-045: ABCI-Evidence](./adr-045-abci-evidence.md) -- [ADR-050: Improved Trusted Peering](./adr-050-improved-trusted-peering.md) -- [ADR-057: RPC](./adr-057-RPC.md) -- [ADR-060: Go-API-Stability](./adr-060-go-api-stability.md) -- [ADR-061: P2P-Refactor-Scope](./adr-061-p2p-refactor-scope.md) -- [ADR-062: P2P-Architecture](./adr-062-p2p-architecture.md) -- [ADR-064: Batch Verification](./adr-064-batch-verification.md) -- [ADR-068: Reverse-Sync](./adr-068-reverse-sync.md) -- [ADR-069: Node Initialization](./adr-069-flexible-node-initialization.md) -- [ADR-073: Adopt LibP2P](./adr-073-libp2p.md) -- [ADR-074: Migrate Timeout Parameters to Consensus Parameters](./adr-074-timeout-params.md) -- [ADR-080: Reverse Sync](./adr-080-reverse-sync.md) diff --git a/docs/references/README.md b/docs/references/README.md new file mode 100644 index 00000000000..ca49f829476 --- /dev/null +++ b/docs/references/README.md @@ -0,0 +1,73 @@ +--- +order: 4 +title: Reference Documentation +description: References +parent: + order: 1 +--- + +# CometBFT Reference Documentation + +Welcome to the CometBFT Reference Documentation, a comprehensive resource for essential information and +standards related to CometBFT. + +In this documentation, you'll find valuable references in three key areas: + +## Architecture Decision Records (ADRs) + +[Architecture Decision Records (ADRs)](./architecture/README.md) provide a structured approach to documenting key architectural +decisions made during the development of CometBFT. These records help us maintain transparency, +share knowledge, and ensure that architectural choices align with CometBFT's goals and constraints. + +### What You'll Find in ADRs: + +- Clear explanations of architectural decisions. +- The context and background that led to each decision. +- Rationale for choosing a particular solution. +- Any associated risks and trade-offs. +- Decision status and tracking for ongoing changes. + +Browse the ADRs to gain insights into the architectural decisions that shape CometBFT. + +## Quality Assurance (QA) Documents + +[Quality Assurance (QA)](./qa/README.md) Documents are the foundation of the commitment to delivering a high-quality CometBFT +implementation. These standards guide the testing processes, quality control measures, and best practices +to ensure that CometBFT meets and exceeds industry benchmarks. + +### What You'll Find in QA: + +- Testing methodologies and strategies. +- Documentation on test plans and test cases. +- Guidelines for test automation. +- Processes for defect tracking and resolution. +- Continuous improvement practices. + +Explore the QA documents to understand the testing methods to ensure the quality and performance of CometBFT. + +## Request for Comments (RFCs) + +[Request for Comments (RFCs)](./rfc/README.md) documents serve as a platform for open and collaborative discussions on proposed +changes, new features, and improvements within CometBFT. RFCs encourage cross-team communication +and feedback, ensuring that decisions are well-informed and aligned with CometBFT's goals. + +### What You'll Find in RFCs: + +- Proposals for changes or enhancements. +- Technical details and specifications. +- Discussions and feedback from team members. +- Status updates and implementation progress. + +Engage with RFCs to participate in shaping the direction of CometBFT, share your insights, +and contribute to its continuous evolution. + +## Explore CometBFT References + +The CometBFT Reference Documentation empowers you with knowledge and information that enhances +your understanding of CometBFT's architecture, quality assurance, and ongoing improvements. +Whether you're a chain developer, application developer, or simply interested in CometBFT, +you'll find valuable insights and documentation here. + +Feel free to explore the sections on ADRs, QA Standards, and RFCs to access the resources you need. +We are committed to transparency, collaboration, and excellence, and this documentation reflects +our dedication to those principles. diff --git a/docs/architecture/README.md b/docs/references/architecture/README.md similarity index 67% rename from docs/architecture/README.md rename to docs/references/architecture/README.md index 0b6ee227431..6b57c9c7ac1 100644 --- a/docs/architecture/README.md +++ b/docs/references/architecture/README.md @@ -21,7 +21,7 @@ provide: - References - Changelog -To create a new ADR, please use the [ADR template](./adr-template.md). +To create a new ADR, please use the [ADR template](adr-template.md). Note the distinction between an ADR and a spec. An ADR provides the context, intuition, reasoning, and justification for a change in architecture, or for the @@ -42,24 +42,24 @@ numbering our ADRs from 100 onwards. ### Proposed -- [ADR-103: Protobuf definition versioning](./adr-103-proto-versioning.md) -- [ADR-105: Refactor list of senders in mempool](./adr-105-refactor-mempool-senders.md) +- [ADR-103: Protobuf definition versioning](adr-103-proto-versioning.md) +- [ADR-105: Refactor list of senders in mempool](adr-105-refactor-mempool-senders.md) ### Accepted -- [ADR-101: Data companion pull API](./adr-101-data-companion-pull-api.md) -- [ADR-104: State sync from local snapshot](./adr-104-out-of-band-state-sync.md) -- [ADR-107: Rename protobuf versions of 0.x releases to pre-v1 betas](./adr-107-betaize-proto-versions.md) -- [ADR-109: Reduce CometBFT Go API Surface Area](./adr-109-reduce-go-api-surface.md) -- [ADR-111: `nop` Mempool](./adr-111-nop-mempool.md) +- [ADR-101: Data companion pull API](adr-101-data-companion-pull-api.md) +- [ADR-104: State sync from local snapshot](adr-104-out-of-band-state-sync.md) +- [ADR-107: Rename protobuf versions of 0.x releases to pre-v1 betas](adr-107-betaize-proto-versions.md) +- [ADR-109: Reduce CometBFT Go API Surface Area](adr-109-reduce-go-api-surface.md) +- [ADR-111: `nop` Mempool](adr-111-nop-mempool.md) ### Implemented -- [ADR-108: E2E tests for CometBFT's behaviour in respect to ABCI 1.0.](./adr-108-e2e-abci++.md) +- [ADR-108: E2E tests for CometBFT's behaviour in respect to ABCI 1.0.](adr-108-e2e-abci++.md) ### Deprecated ### Rejected -- [ADR-100: Data companion push API](./adr-100-data-companion-push-api.md) -- [ADR-110: Remote mempool](./adr-110-remote-mempool.md) +- [ADR-100: Data companion push API](adr-100-data-companion-push-api.md) +- [ADR-110: Remote mempool](adr-110-remote-mempool.md) diff --git a/docs/architecture/adr-100-data-companion-push-api.md b/docs/references/architecture/adr-100-data-companion-push-api.md similarity index 99% rename from docs/architecture/adr-100-data-companion-push-api.md rename to docs/references/architecture/adr-100-data-companion-push-api.md index d743714b394..5e04b3595b3 100644 --- a/docs/architecture/adr-100-data-companion-push-api.md +++ b/docs/references/architecture/adr-100-data-companion-push-api.md @@ -505,7 +505,7 @@ PostgreSQL). [\#7471]: https://github.com/tendermint/tendermint/issues/7471 [rfc-003]: ../rfc/tendermint-core/rfc-003-performance-questions.md [rfc-006]: ../rfc/tendermint-core/rfc-006-event-subscription.md -[adr-075]: ./tendermint-core/adr-075-rpc-subscription.md +[adr-075]: tendermint-core/adr-075-rpc-subscription.md [websocket-api]: https://docs.cometbft.com/v0.34/rpc/#/Websocket [`/tx_search`]: https://docs.cometbft.com/v0.34/rpc/#/Info/tx_search [`/block_search`]: https://docs.cometbft.com/v0.34/rpc/#/Info/block_search diff --git a/docs/architecture/adr-101-data-companion-pull-api.md b/docs/references/architecture/adr-101-data-companion-pull-api.md similarity index 97% rename from docs/architecture/adr-101-data-companion-pull-api.md rename to docs/references/architecture/adr-101-data-companion-pull-api.md index 963dd578beb..b941ae5b54f 100644 --- a/docs/architecture/adr-101-data-companion-pull-api.md +++ b/docs/references/architecture/adr-101-data-companion-pull-api.md @@ -278,7 +278,7 @@ message GetBlockResultsRetainHeightResponse { ##### Indexer pruning service This gRPC service can be used to instruct CometBFT to prune the transaction and -block events indexed by CometBFT. +block events indexed by CometBFT. To support this, the above described pruning service is extended as follows: @@ -418,13 +418,13 @@ interaction between a node and its data companion: is influenced by the application and pruning service block retain heights. - `abci_results_base_height` - The actual base height of stored block results, which is influenced by the pruning service block results retain height. -- `block_indexer_retain_height` - The current block indexer retain height +- `block_indexer_retain_height` - The current block indexer retain height requested by the pruning service. -- `tx_indexer_retain_height` - The current tx indexer retain height +- `tx_indexer_retain_height` - The current tx indexer retain height requested by the pruning service. -- `block_indexer_base_height` - The minimum height at which we have block events +- `block_indexer_base_height` - The minimum height at which we have block events (should demonstrate the effects of pruning the block indexer) -- `tx_indexer_base_height` - The minimum height at which we have transaction events +- `tx_indexer_base_height` - The minimum height at which we have transaction events (should demonstrate the effects of pruning the tx indexer) Other metrics may be proposed as part of the non-privileged gRPC API that could @@ -463,10 +463,10 @@ companion, but only if the data companion is the exclusive user of those APIs. - [\#81 - rpc: Add gRPC support][\#81] - [Documentation on current implementation of ADR-101][dc-docs] -[adr-100-context]: ./adr-100-data-companion-push-api.md#context -[adr-100]: ./adr-100-data-companion-push-api.md -[adr-100-req]: ./adr-100-data-companion-push-api.md#requirements -[adr-100-alt]: ./adr-100-data-companion-push-api.md#alternative-approaches +[adr-100-context]: adr-100-data-companion-push-api.md#context +[adr-100]: adr-100-data-companion-push-api.md +[adr-100-req]: adr-100-data-companion-push-api.md#requirements +[adr-100-alt]: adr-100-data-companion-push-api.md#alternative-approaches [\#81]: https://github.com/cometbft/cometbft/issues/81 -[abci-commit]: ../../spec/abci/abci++_methods.md#commit -[dc-docs]: https://github.com/cometbft/cometbft/tree/main/docs/data-companion \ No newline at end of file +[abci-commit]: ../../../spec/abci/abci++_methods.md#commit +[dc-docs]: https://github.com/cometbft/cometbft/tree/main/docs/data-companion diff --git a/docs/architecture/adr-103-proto-versioning.md b/docs/references/architecture/adr-103-proto-versioning.md similarity index 100% rename from docs/architecture/adr-103-proto-versioning.md rename to docs/references/architecture/adr-103-proto-versioning.md diff --git a/docs/architecture/adr-104-out-of-band-state-sync.md b/docs/references/architecture/adr-104-out-of-band-state-sync.md similarity index 91% rename from docs/architecture/adr-104-out-of-band-state-sync.md rename to docs/references/architecture/adr-104-out-of-band-state-sync.md index ce4eb356e1f..d8ef8c9502b 100644 --- a/docs/architecture/adr-104-out-of-band-state-sync.md +++ b/docs/references/architecture/adr-104-out-of-band-state-sync.md @@ -28,7 +28,7 @@ of its weaknesses. In fact, while downloading recent snapshots is very convenient for new nodes (clients of the protocol), providing snapshots to multiple peers (as servers of the protocol) is _bandwidth-consuming_, especially without a clear incentive for -node operators to provide this service. +node operators to provide this service. As a result, the number of nodes in production CometBFT networks offering the state sync service (i.e., servers offering snapshots) has been limited, which has rendered the service _fragile_ (from the client's point of view). In other words, it is very @@ -48,22 +48,22 @@ sync and/or Consensus to catch up with the latest state of the network. The purpose of this ADR is to provide node operators with more flexibility in defining how or where state sync should look for application snapshots. More precisely, it enables state sync to support the bootstrap of nodes from -application snapshots obtained _out-of-band_ by operators, available to the +application snapshots obtained _out-of-band_ by operators, available to the node _locally_. Applications dump snapshots into an exportable format, which can be then obtained -by the operators and placed on the syncing node. The node can then sync locally +by the operators and placed on the syncing node. The node can then sync locally without transferring snapshots via the network. The goal is to provide an alternative to the mechanism currently adopted by state sync, discovering and fetching application snapshots from peers in the network, in order to address the above mentioned limitations, while preserving -most of state sync's operation. +most of state sync's operation. The ADR presents two solutions: -1. The first solution is implemented by the application and was proposed and -implemented by the Cosmos SDK (PR [#16067][sdk-pr2] and [#16061][sdk-pr1] ). This ADR describes the solution +1. The first solution is implemented by the application and was proposed and +implemented by the Cosmos SDK (PR [#16067][sdk-pr2] and [#16061][sdk-pr1] ). This ADR describes the solution in a general way, proividing guidelines to non-SDK based applications if they wish -to implement their own local state sync. +to implement their own local state sync. 2. The second part of the ADR proposes a more general solution, that uses ABCI to achieve the same behavior provided by the SDK's solution. @@ -124,14 +124,14 @@ handled by state sync, [ADR 083][adr083]/[ADR 103][adr103] assumes that node operators are able to manually synchronize the application state from a running node (it might be necessary to stop it) to a not-yet-started fresh node. -The main limitation of the approach in [ADR 083][adr083]/[ADR 103][adr103] +The main limitation of the approach in [ADR 083][adr083]/[ADR 103][adr103] is that it relies on the ability of node operators to properly synchronize the application state between two nodes. While experienced node operators are likely able to perform this operation in a proper way, we have to consider a broader set of users and emphasize that it is -an operation susceptible to errors. Operators need to know the format of the +an operation susceptible to errors. Operators need to know the format of the application's stored state, export the state properly and guarantee consistency. That is, -they have to make sure that nobody is trying to read the exported state while they are +they have to make sure that nobody is trying to read the exported state while they are exporting it. Furthermore, it is an operation that is, by definition, application-specific: applications are free to manage their state as they see fit, and this includes @@ -144,7 +144,7 @@ in order to adopt this solution. State sync should support the bootstrap of new nodes from application snapshots available locally. Implementing this option does not mean that networked State sync -should be removed, but not both should be enabled at the same time. +should be removed, but not both should be enabled at the same time. In other words, the following operation should be, in general terms, possible: @@ -162,22 +162,22 @@ In other words, the following operation should be, in general terms, possible: As Cosmos SDK implemented a solution for all applications using it, and we do not have non-SDK in production users requesting this feature, at the moment we will not implement the generally applicable -solution. +solution. -This ADR will outline both the solution implemented by the SDK and a design proposal of a +This ADR will outline both the solution implemented by the SDK and a design proposal of a generally applicable solution, that can be later on picked up and implemented in CometBFT. ## Detailed Design ### Application-implemented local state sync -This section describes the solution to local state sync implemented by the SDK. An application can +This section describes the solution to local state sync implemented by the SDK. An application can chose to implement local state sync differently, or implement only a subset of the functionalities implemented by the SDK. This solution exposes a command line interface enabling a node to manipulate the snapshots including dumping existing snapshots to an exportable format, loading, restoring and deleting exported snapshots, -as well as a command to bootstrap the node by resetting CometBFT's state and block store. +as well as a command to bootstrap the node by resetting CometBFT's state and block store. The SDK exposes the following commands for snapshot manipulation: @@ -201,32 +201,32 @@ comet bootstrap-state Bootstrap the state of CometBFT's state and block ``` -These commands enable the implementation of both the client and server side of statesync. +These commands enable the implementation of both the client and server side of statesync. Namely, a statesync server can use `dump` to create a portable archive format out existing snapshots, -or trigger snapshot creation using `export`. +or trigger snapshot creation using `export`. The client side, restores the application state from a local snapshot that was previously exported, using `restore`. Before `restore` can be called, the client has to `load` an archived snapshot into its local snapshot store. Upon successful completion of the previous sequence of commands, the state of CometBFT is bootstrapped -using `bootstrap-state` and CometBFT can be launched. +using `bootstrap-state` and CometBFT can be launched. There are three prerequisites for this solution to work when a node is syncing: 1. The application has access to the snapshot store (usually as a separate database used by applications) 2. CometBFT's state and block stores are empty or reset -3. CometBFT is not running while the node is state syncing +3. CometBFT is not running while the node is state syncing The server side of state sync (snapshot generation and dumping), can be performed while the node is running. The application has to be careful not to interfere with normal node operations, and to use a snapshot store -and dumping mechanism that will mitigate the risk of requesting snapshots while they are being dumped to an archive format. +and dumping mechanism that will mitigate the risk of requesting snapshots while they are being dumped to an archive format. -In order to be able to dump or export the snapshots, the application must have access to the snapshot store. +In order to be able to dump or export the snapshots, the application must have access to the snapshot store. We describe the main interface expected from the snapshot database and used by the above mentioned CLI commands -for snapshot manipulation. -The interface was derived from the SDK's implementation of local State sync. +for snapshot manipulation. +The interface was derived from the SDK's implementation of local State sync. ```golang @@ -234,7 +234,7 @@ The interface was derived from the SDK's implementation of local State sync. func (s *Store) Delete(height uint64, format uint32) error // Retrieves a snapshot for a certain height -func (s *Store) Get(height uint64, format uint32) (*Snapshot, error) +func (s *Store) Get(height uint64, format uint32) (*Snapshot, error) // List recent snapshots, in reverse order (newest first) func (s *Store) List() ([]*Snapshot, error) @@ -248,30 +248,30 @@ func (s *Store) Load(height uint64, format uint32) (*Snapshot, <-chan io.ReadClo func (s *Store) LoadChunk(height uint64, format, chunk uint32) (io.ReadCloser, error) // Save saves a snapshot to disk, returning it. -func (s *Store) Save(height uint64, format uint32, chunks <-chan io.ReadCloser) (*Snapshot, error) +func (s *Store) Save(height uint64, format uint32, chunks <-chan io.ReadCloser) (*Snapshot, error) // PathChunk generates a snapshot chunk path. func (s *Store) PathChunk(height uint64, format, chunk uint32) string ``` -In order to dump a snapshot, an application needs to retrieve all the chunks stored at a certain path. +In order to dump a snapshot, an application needs to retrieve all the chunks stored at a certain path. #### CometBFT state bootstrap In addition to managing snapshots, it is necessary to bootstrap (setup) the state and block store of CometBFT before starting up the node. -Upon a successful start, CometBFT performs block sync and consensus. +Upon a successful start, CometBFT performs block sync and consensus. At the moment of writing this ADR, there is no command line in CometBFT that supports this, but an [issue][state-bootstrap] has been opened to address this. Until it has been resolved, the application developers have to, within their bootstrapping command: - Create a state and block store - Launch a light client to obtain and verify the block header for the snapshot's height. -- Use the light client's `State` to +- Use the light client's `State` to verify that the `AppHash` on the retrieved block header matches the `AppHash` obtained via -the ABCI `Info` call to the application (the same procedure is performed by the node on startup). -- Use `Commit` to retrieve the last commit for the snapshot's height. -- Save the retrieved values into the state and block stores. +the ABCI `Info` call to the application (the same procedure is performed by the node on startup). +- Use `Commit` to retrieve the last commit for the snapshot's height. +- Save the retrieved values into the state and block stores. This code essentially mimics what CometBFT does as part of node setup, once state sync is complete. @@ -281,44 +281,44 @@ This code essentially mimics what CometBFT does as part of node setup, once stat Given that snapshot manipulation is entirely application defined, and to avoid pulling this functionality into CometBFT, we propose a solution using ABCI, that mimics the behaviour described in the previous section. -On the client side, the main difference between local State sync done by the application and CometBFT is that the +On the client side, the main difference between local State sync done by the application and CometBFT is that the application has to perform the sync offline, in order to properly set up CometBFT's initial state. Furthermore, the -application developer has to manually bootstrap CometBFTs state and block stores. +application developer has to manually bootstrap CometBFTs state and block stores. With support for local State sync, a node can simply load a snapshot from a predefined location and offer it to the application -as is currently done via networked State sync. +as is currently done via networked State sync. On the server side, without any support for local State sync, an operator has to manually instruct the application -to export the snapshots into a portable format (via `dump`). +to export the snapshots into a portable format (via `dump`). -Having support for this within CometBFT, the app can automatically perform this export when taking snapshots. +Having support for this within CometBFT, the app can automatically perform this export when taking snapshots. In order to support local State sync, the following changes to CometBFT are necessary: 1. Adding new configuration options to the config file. -2. Introduce a CLI command that can explicitly tell the application to create a snapshot export, in case +2. Introduce a CLI command that can explicitly tell the application to create a snapshot export, in case operators decide not to generate periodical exports. 3. Extract a snapshot from the exported format. -4. Potentially alter existing ABCI calls to signal to the application that we want to create a snapshot export periodically. +4. Potentially alter existing ABCI calls to signal to the application that we want to create a snapshot export periodically. 5. Allow reading a snapshot from a compressed format into CometBFT and offer it to the application via -the existing `OfferSnapshot` ABCI call. +the existing `OfferSnapshot` ABCI call. At a very high level, there are two possible solutions and we will present both: 1. The application will export snapshots into an exportable format on the server side. When a node syncs up, CometBFT will -send this as a blob of bytes to the application to uncompress and apply the snapshot. +send this as a blob of bytes to the application to uncompress and apply the snapshot. 2. CometBFT creates a snapshot using existing ABCI calls and exports it into a format of our choosing. CometBFT is then in charge of -reading in and parsing the exported snapshot into a snapshot that can be offered to the application via the existing `OfferSnapshot` +reading in and parsing the exported snapshot into a snapshot that can be offered to the application via the existing `OfferSnapshot` and `ApplyChunk` methods. This option does not alter any current APIs and is a good candidate for an initial implementation. - + #### Config file additions ```bash [statesync] # State syncing from a local snapshot -local_sync=false +local_sync=false # Path to snapshot, will be ignored if local_sync=false snapshot_load_path="" # Periodically dump snapshots into archive format (optional) @@ -344,10 +344,10 @@ as snapshot generation, dumping and loading a local snapshot would be built into The `dump` command can be implemented in two ways: -1. Rely on the existing ABCI functions `ListSnapshots` and `LoadChunks` to retrieve the snapshots and chunks from a peer. +1. Rely on the existing ABCI functions `ListSnapshots` and `LoadChunks` to retrieve the snapshots and chunks from a peer. This approach requires no change to the current API and is easy to implement. Furthermore, CometBFT has complete control -over the format of the exported snapshot. It does however involve more than one ABCI call and network data transfer. -2. Extend `RequestListSnapshots` with a flag to indicate that we want an exportable snapshot format and extend `ResponseListSnapshot` to return a +over the format of the exported snapshot. It does however involve more than one ABCI call and network data transfer. +2. Extend `RequestListSnapshots` with a flag to indicate that we want an exportable snapshot format and extend `ResponseListSnapshot` to return a path and format of the exported snapshots. An improvement to the second option mentioned above would be to add path parameters to the command, @@ -360,18 +360,18 @@ A third option is the introduction of a new ABCI call: `ExportSnapshots`, which #### *Automatic snapshot exporting* Applications generate snapshots with a regular cadence (fixed time intervals or heights). The application itself measures the time or number of heights passed since the last snapshot, -and CometBFT has no role in instructing the application when to take snapshots. +and CometBFT has no role in instructing the application when to take snapshots. -The State sync reactor currently retrieves a list of snapshots from a peer, who obtains these snapshots from the local instance of the application using the ABCI `RequestListSnapshots` call. +The State sync reactor currently retrieves a list of snapshots from a peer, who obtains these snapshots from the local instance of the application using the ABCI `RequestListSnapshots` call. Applications can thus themselves be in charge of dumping the snapshots into a given file format, the same way they generate snapshots. - If `auto_snapshot_dump` is true, + If `auto_snapshot_dump` is true, CometBFT instructs the application to export the snapshots periodically. -An alternative solution is that CometBFT, itself, using the implementation of the `dump` command, whichever -is chosen at the time, creates or asks the application to create snapshot exports. This is not forcing the +An alternative solution is that CometBFT, itself, using the implementation of the `dump` command, whichever +is chosen at the time, creates or asks the application to create snapshot exports. This is not forcing the application to create a snapshot at the time of he request, rather *dumps* existing snapshots into -an exportable file format. +an exportable file format. **Export file consistency** @@ -385,17 +385,17 @@ If it is the application that exports the snapshots, it is something the applica #### Syncing a node using local snapshots On startup, if `local_sync` is set to `true`, CometBFT will look for an existing snapshot at the path -given by the operator. If a snapshot is available, it will be loaded and state restored as if it came from a peer in the current implementation. +given by the operator. If a snapshot is available, it will be loaded and state restored as if it came from a peer in the current implementation. Note that, if it is not CometBFT that created the snapshot export from the data retrieved via ABCI (a combination of `ListSnapshots` and `LoadChunks`), CometBFT might not be aware of how the snapshot was exported, and needs to ask the application to restore the snapshot. -If a snapshot was created using option 1 (by CometBFT) from the previous section, or the export format is known to CometBFT (like `tar, gzip` etc.), -CometBFT can extract the snapshot itself, and offer it to the application via `RequestOfferSnapshot` without any API changes. +If a snapshot was created using option 1 (by CometBFT) from the previous section, or the export format is known to CometBFT (like `tar, gzip` etc.), +CometBFT can extract the snapshot itself, and offer it to the application via `RequestOfferSnapshot` without any API changes. -If CometBFT is **not** the one who created the exported file, we introduce a new ABCI call `UnpackSnapshot` -to send the exported snapshot as a blob of bytes to the application, which uncompresses it, installs it -and responds whether the snapshot is accepted (as in `OfferSnapshot`) and the chunks application has passed (as in `LoadChunk`). +If CometBFT is **not** the one who created the exported file, we introduce a new ABCI call `UnpackSnapshot` +to send the exported snapshot as a blob of bytes to the application, which uncompresses it, installs it +and responds whether the snapshot is accepted (as in `OfferSnapshot`) and the chunks application has passed (as in `LoadChunk`). * **Request**: @@ -410,7 +410,7 @@ and responds whether the snapshot is accepted (as in `OfferSnapshot`) and the ch | Name | Type | Description | Field Number | |--------------------|-------------------------------------------------------- |----------------------------------------|--------------| - | result | [Result](../../spec/abci/abci%2B%2B_methods.md#result) | The result of the snapshot offer. | 1 | + | result | [Result](../../../spec/abci/abci++_methods.md#result) | The result of the snapshot offer. | 1 | | resultChunk | ResultC | The result of applying the chunks. | 2 | ```proto @@ -423,12 +423,12 @@ and responds whether the snapshot is accepted (as in `OfferSnapshot`) and the ch } ``` -Unlike networked state sync, we do not re-fetch individual chunks, thus if the application of a chunk fails, then the application of the whole snapshot fails. +Unlike networked state sync, we do not re-fetch individual chunks, thus if the application of a chunk fails, then the application of the whole snapshot fails. ## Consequences Adding the support for a node to sync up using a local snapshot can speed up the syncing process, especially as -network based State sync has proven to be fragile. +network based State sync has proven to be fragile. ### Positive @@ -440,7 +440,7 @@ network based State sync has proven to be fragile. ### Negative -- Implementing additional ABCI functions is API breaking and might not be backwards compatible. +- Implementing additional ABCI functions is API breaking and might not be backwards compatible. ### Neutral diff --git a/docs/architecture/adr-105-refactor-mempool-senders.md b/docs/references/architecture/adr-105-refactor-mempool-senders.md similarity index 100% rename from docs/architecture/adr-105-refactor-mempool-senders.md rename to docs/references/architecture/adr-105-refactor-mempool-senders.md diff --git a/docs/architecture/adr-107-betaize-proto-versions.md b/docs/references/architecture/adr-107-betaize-proto-versions.md similarity index 100% rename from docs/architecture/adr-107-betaize-proto-versions.md rename to docs/references/architecture/adr-107-betaize-proto-versions.md diff --git a/docs/architecture/adr-108-e2e-abci++.md b/docs/references/architecture/adr-108-e2e-abci++.md similarity index 82% rename from docs/architecture/adr-108-e2e-abci++.md rename to docs/references/architecture/adr-108-e2e-abci++.md index cc7ce13ad62..cff9934f119 100644 --- a/docs/architecture/adr-108-e2e-abci++.md +++ b/docs/references/architecture/adr-108-e2e-abci++.md @@ -16,20 +16,20 @@ In order to demonstrate that CometBFT behaves as expected from the viewpoint of Issue: [353](https://github.com/cometbft/cometbft/issues/353). -Current version, ABCI 1.0, does not support vote extensions (ABCI 2.0). However, this is the next step. +Current version, ABCI 1.0, does not support vote extensions (ABCI 2.0). However, this is the next step. ## Decision ### 1) ABCI 1.0 requests logging -The idea was to do this at the Application side. Every time the Application +The idea was to do this at the Application side. Every time the Application receives a request, it logs it. **Implementation** -The rationale behind this part of the implementation was to log the request concisely and use the existing structures as much as possible. +The rationale behind this part of the implementation was to log the request concisely and use the existing structures as much as possible. -Whenever an ABCI 1.0 request is made, the application will create `abci.Request` (`abci` stands for `"github.com/cometbft/cometbft/abci/types"`) and log it. The example is below. +Whenever an ABCI 1.0 request is made, the application will create `abci.Request` (`abci` stands for `"github.com/cometbft/cometbft/abci/types"`) and log it. The example is below. ```go func (app *Application) InitChain(_ context.Context, req *abci.RequestInitChain) (*abci.ResponseInitChain, error) { @@ -39,13 +39,13 @@ func (app *Application) InitChain(_ context.Context, req *abci.RequestInitChain) if err != nil { return nil, err } - + ... } ``` -Notice here that we create an empty `abci.RequestInitChain` object while we can also use the one passed to the `InitChain` function. The reason behind this is that, at the moment, we do not need specific fields of the request; we just need to be able to extract the information about the request type. For this, an empty object of a particular type is enough. +Notice here that we create an empty `abci.RequestInitChain` object while we can also use the one passed to the `InitChain` function. The reason behind this is that, at the moment, we do not need specific fields of the request; we just need to be able to extract the information about the request type. For this, an empty object of a particular type is enough. -The `app.logABCIRequest(r)` function is a new function implemented in the same file (`test/e2e/app/app.go`). If the `ABCIRequestsLoggingEnabled` flag is set to `true`, set automatically when ABCI 1.0 tests are enabled, it logs received requests. The full implementation is the following: +The `app.logABCIRequest(r)` function is a new function implemented in the same file (`test/e2e/app/app.go`). If the `ABCIRequestsLoggingEnabled` flag is set to `true`, set automatically when ABCI 1.0 tests are enabled, it logs received requests. The full implementation is the following: ```go func (app *Application) logABCIRequest(req *abci.Request) error { @@ -62,7 +62,7 @@ func (app *Application) logABCIRequest(req *abci.Request) error { ``` `GetABCIRequestString(req)` is a new method that receives a request and returns its string representation. The implementation and tests for this function and the opposite function `GetABCIRequestFromString(req)` -that returns `abci.Request` from the string are provided in files `test/e2e/app/log.go` and `test/e2e/app/log_test.go`, respectively. To create a string representation of a request, we first marshal the request via `proto.Marshal()` method and then convert received bytes in the string using `base64.StdEncoding.EncodeToString()` method. In addition, we surround the new string with `abci-req` constants so that we can find lines with ABCI 1.0 request more easily. The code of the method is below: +that returns `abci.Request` from the string are provided in files `test/e2e/app/log.go` and `test/e2e/app/log_test.go`, respectively. To create a string representation of a request, we first marshal the request via `proto.Marshal()` method and then convert received bytes in the string using `base64.StdEncoding.EncodeToString()` method. In addition, we surround the new string with `abci-req` constants so that we can find lines with ABCI 1.0 request more easily. The code of the method is below: ```go func GetABCIRequestString(req *abci.Request) (string, error) { @@ -76,31 +76,31 @@ func GetABCIRequestString(req *abci.Request) (string, error) { } ``` -*Note:* At the moment, we are not compressing the marshalled request before converting it to `base64` `string` because we are logging the empty requests that take at most 24 bytes. However, if we decide to log the actual requests in the future, we might want to compress them. Based on a few tests, we observed that the size of a request can go up to 7KB. +*Note:* At the moment, we are not compressing the marshalled request before converting it to `base64` `string` because we are logging the empty requests that take at most 24 bytes. However, if we decide to log the actual requests in the future, we might want to compress them. Based on a few tests, we observed that the size of a request can go up to 7KB. -If in the future we want to log another ABCI 1.0 request type, we just need to do the same thing: -create a corresponding `abci.Request` and log it via -`app.logABCIRequest(r)`. +If in the future we want to log another ABCI 1.0 request type, we just need to do the same thing: +create a corresponding `abci.Request` and log it via +`app.logABCIRequest(r)`. ### 2) Parsing the logs -We need a code that will take the logs from all nodes and collect the ABCI 1.0 requests that were logged by the application. +We need a code that will take the logs from all nodes and collect the ABCI 1.0 requests that were logged by the application. **Implementation** This logic is implemented inside the `fetchABCIRequests(t *testing.T, nodeName string)` function that resides in `test/e2e/tests/e2e_test.go` file. This function does three things: -- Takes the output of a specific node in the testnet from the moment we launched the testnet until the function is called. The node name is passed as a function parameter. It uses the `docker-compose logs` and `grep nodeName` commands. +- Takes the output of a specific node in the testnet from the moment we launched the testnet until the function is called. The node name is passed as a function parameter. It uses the `docker-compose logs` and `grep nodeName` commands. - Parses the logs line by line and extracts the `abci.Request`, if one exists. The request is received by forwarding each line to the `app.GetABCIRequestFromString(req)` method. - Returns the array of slices where each slice contains the set of `abci.Request`s logged on that node. Every time a crash happens, a new array element (new slice `[]*abci.Request`) will be created. We know a crash has happened because we log "Application started" every time the application starts. Specifically, we added this log inside `NewApplication()` function in `test/e2e/app/app.go` file. In the end, `fetchABCIRequests()` will return just one slice if the node did not experience any crashes and $n+1$ slices if there were $n$ crashes. The benefit of logging the requests in the previously described way is that now we can use `[]*abci.Request` to store ABCI 1.0 requests of any type. - + ### 3) ABCI 1.0 grammar checker -The idea here was to find a library that automatically verifies whether a specific execution respects the prescribed grammar. +The idea here was to find a library that automatically verifies whether a specific execution respects the prescribed grammar. **Implementation** -We found the following library - https://github.com/goccmack/gogll. It generates a GLL or LR(1) parser and an FSA-based lexer for any context-free grammar. What we needed to do is to rewrite [ABCI 1.0 grammar](../../spec/abci/abci%2B%2B_comet_expected_behavior.md#valid-method-call-sequences) -using the syntax that the library understands. +We found the following library - https://github.com/goccmack/gogll. It generates a GLL or LR(1) parser and an FSA-based lexer for any context-free grammar. What we needed to do is to rewrite [ABCI 1.0 grammar](../../../spec/abci/abci++_comet_expected_behavior.md#valid-method-call-sequences) +using the syntax that the library understands. The new grammar is below and can be found in `test/e2e/pkg/grammar/abci_grammar.md` file. ```abnf @@ -108,11 +108,11 @@ The new grammar is below and can be found in `test/e2e/pkg/grammar/abci_grammar. Start : CleanStart | Recovery; CleanStart : InitChain ConsensusExec | StateSync ConsensusExec ; -StateSync : StateSyncAttempts SuccessSync | SuccessSync ; +StateSync : StateSyncAttempts SuccessSync | SuccessSync ; StateSyncAttempts : StateSyncAttempt | StateSyncAttempt StateSyncAttempts ; StateSyncAttempt : OfferSnapshot ApplyChunks | OfferSnapshot ; -SuccessSync : OfferSnapshot ApplyChunks ; -ApplyChunks : ApplyChunk | ApplyChunk ApplyChunks ; +SuccessSync : OfferSnapshot ApplyChunks ; +ApplyChunks : ApplyChunk | ApplyChunk ApplyChunks ; Recovery : InitChain ConsensusExec | ConsensusExec ; @@ -120,46 +120,46 @@ ConsensusExec : ConsensusHeights ; ConsensusHeights : ConsensusHeight | ConsensusHeight ConsensusHeights ; ConsensusHeight : ConsensusRounds FinalizeBlock Commit | FinalizeBlock Commit ; ConsensusRounds : ConsensusRound | ConsensusRound ConsensusRounds ; -ConsensusRound : Proposer | NonProposer ; +ConsensusRound : Proposer | NonProposer ; -Proposer : PrepareProposal | PrepareProposal ProcessProposal ; +Proposer : PrepareProposal | PrepareProposal ProcessProposal ; NonProposer: ProcessProposal ; InitChain : "init_chain" ; -FinalizeBlock : "finalize_block" ; +FinalizeBlock : "finalize_block" ; Commit : "commit" ; OfferSnapshot : "offer_snapshot" ; -ApplyChunk : "apply_snapshot_chunk" ; -PrepareProposal : "prepare_proposal" ; +ApplyChunk : "apply_snapshot_chunk" ; +PrepareProposal : "prepare_proposal" ; ProcessProposal : "process_proposal" ; - + ``` -If you compare this grammar with the original one, you will notice that, in addition to vote extensions, -`Info` is removed. The reason is that, as explained in the section [CometBFT's expected behaviour](../../spec/abci/abci%2B%2B_comet_expected_behavior.md#valid-method-call-sequences), one of the -purposes of the `Info` method is being part of the RPC handling from an external -client. Since this can happen at any time, it complicates the -grammar. -This is not true in other cases, but since the Application does -not know why the `Info` is called, we removed -it totally from the new grammar. The Application is still logging the `Info` +If you compare this grammar with the original one, you will notice that, in addition to vote extensions, +`Info` is removed. The reason is that, as explained in the section [CometBFT's expected behaviour](../../../spec/abci/abci++_comet_expected_behavior.md#valid-method-call-sequences), one of the +purposes of the `Info` method is being part of the RPC handling from an external +client. Since this can happen at any time, it complicates the +grammar. +This is not true in other cases, but since the Application does +not know why the `Info` is called, we removed +it totally from the new grammar. The Application is still logging the `Info` call, but a specific test would need to be written to check whether it happens -at the right moment. +at the right moment. -Moreover, it is worth noticing that the `(inf)` part of the grammar is replaced with the `*`. This results in the new grammar being finite compared to the original, which represents an infinite (omega) grammar. +Moreover, it is worth noticing that the `(inf)` part of the grammar is replaced with the `*`. This results in the new grammar being finite compared to the original, which represents an infinite (omega) grammar. -The `gogll` library receives the file with the grammar as input, and it generates the corresponding parser and lexer. The actual commands are integrated into `test/e2e/Makefile` and executed when `make grammar-gen` is invoked. -The resulting code is stored inside `test/e2e/pkg/grammar/grammar-auto` directory. +The `gogll` library receives the file with the grammar as input, and it generates the corresponding parser and lexer. The actual commands are integrated into `test/e2e/Makefile` and executed when `make grammar-gen` is invoked. +The resulting code is stored inside `test/e2e/pkg/grammar/grammar-auto` directory. Apart from this auto-generated code, we implemented `GrammarChecker` abstraction which knows how to use the generated parsers and lexers to verify whether a specific execution (list of ABCI 1.0 calls logged by the Application while the -testnet was running) respects the ABCI 1.0 grammar. The implementation and tests -for it are inside `test/e2e/pkg/grammar/checker.go` and -`test/e2e/pkg/grammar/checker_test.go`, respectively. +testnet was running) respects the ABCI 1.0 grammar. The implementation and tests +for it are inside `test/e2e/pkg/grammar/checker.go` and +`test/e2e/pkg/grammar/checker_test.go`, respectively. How the `GrammarChecker` works is demonstrated with the test `TestCheckABCIGrammar` -implemented in `test/e2e/tests/abci_test.go` file. +implemented in `test/e2e/tests/abci_test.go` file. ```go func TestCheckABCIGrammar(t *testing.T) { @@ -179,21 +179,21 @@ func TestCheckABCIGrammar(t *testing.T) { } ``` -Specifically, the test first creates a `GrammarChecker` object. Then for each node in the testnet, it collects all requests -logged by this node. Remember here that `fetchABCIRequests()` returns an array of slices(`[]*abci.Request`) where the slice -with index 0 corresponds to the node's `CleanStart` execution, and each additional slice corresponds to the `Recovery` -execution after a specific crash. Each node must have one `CleanStart` execution and the same number of `Recovery` executions -as the number of crashes that happened on this node. If collecting was successful, the test checks whether each execution -respects the ABCI 1.0 -grammar by calling `checker.Verify()` method. If `Verify` returns an error, the specific execution does not respect the -grammar, and the test will fail. - -The tests are executed only if `ABCITestsEnabled` is set to `true`. This is done through the manifest file. Namely, if we -want to test whether CometBFT respects ABCI 1.0 grammar, we would need to enable these tests by adding `abci_tests_enabled = -true` in the manifest file of a particular testnet (e.g. `networks/ci.toml`). This will automatically activate logging on the -application side. - -The `Verify()` method is shown below. +Specifically, the test first creates a `GrammarChecker` object. Then for each node in the testnet, it collects all requests +logged by this node. Remember here that `fetchABCIRequests()` returns an array of slices(`[]*abci.Request`) where the slice +with index 0 corresponds to the node's `CleanStart` execution, and each additional slice corresponds to the `Recovery` +execution after a specific crash. Each node must have one `CleanStart` execution and the same number of `Recovery` executions +as the number of crashes that happened on this node. If collecting was successful, the test checks whether each execution +respects the ABCI 1.0 +grammar by calling `checker.Verify()` method. If `Verify` returns an error, the specific execution does not respect the +grammar, and the test will fail. + +The tests are executed only if `ABCITestsEnabled` is set to `true`. This is done through the manifest file. Namely, if we +want to test whether CometBFT respects ABCI 1.0 grammar, we would need to enable these tests by adding `abci_tests_enabled = +true` in the manifest file of a particular testnet (e.g. `networks/ci.toml`). This will automatically activate logging on the +application side. + +The `Verify()` method is shown below. ```go func (g *Checker) Verify(reqs []*abci.Request, isCleanStart bool) (bool, error) { if len(reqs) == 0 { @@ -214,26 +214,26 @@ func (g *Checker) Verify(reqs []*abci.Request, isCleanStart bool) (bool, error) ``` It receives a set of ABCI 1.0 requests and a flag saying whether they represent a `CleanStart` execution or not and does the following things: -- Checks if the execution is an empty execution. -- Filter the requests by calling the method `filterRequests()`. This method will remove all the requests from the set that are not supported by the current version of the grammar. In addition, it will filter the last height by removing all ABCI 1.0 requests after the -last `Commit`. The function `fetchABCIRequests()` can be called in the middle of the height. As a result, the last height may be incomplete and -classified as invalid, even if that is not the reality. The simple example here is that the last -request fetched via `fetchABCIRequests()` is `FinalizeBlock`; however, `Commit` happens after +- Checks if the execution is an empty execution. +- Filter the requests by calling the method `filterRequests()`. This method will remove all the requests from the set that are not supported by the current version of the grammar. In addition, it will filter the last height by removing all ABCI 1.0 requests after the +last `Commit`. The function `fetchABCIRequests()` can be called in the middle of the height. As a result, the last height may be incomplete and +classified as invalid, even if that is not the reality. The simple example here is that the last +request fetched via `fetchABCIRequests()` is `FinalizeBlock`; however, `Commit` happens after `fetchABCIRequests()` was invoked. Consequently, the execution -will be considered as faulty because `Commit` is missing, even though the `Commit` -will happen after. This is why if the execution consists of only one incomplete height and function `filterRequests()` returns an empty set of requests, the `Verify()` method considers this execution as valid and returns `true`. -- Generates an execution string by replacing `abci.Request` with the +will be considered as faulty because `Commit` is missing, even though the `Commit` +will happen after. This is why if the execution consists of only one incomplete height and function `filterRequests()` returns an empty set of requests, the `Verify()` method considers this execution as valid and returns `true`. +- Generates an execution string by replacing `abci.Request` with the corresponding terminal from the grammar. This logic is implemented in -`getExecutionString()` function. This function receives a list of `abci.Request` and generates a string where every request -will be replaced with a corresponding terminal. For example, request `r` of type `abci.Request_PrepareProposal` is replaced with the string `prepare_proposal`, the first part of `r`'s string representation. -- Checks if the resulting string with terminals respects the grammar by calling the -`verify()` function. The implementations of both functions are the same; they just use different parsers and lexers. -- Returns true if the execution is valid and an error if that's not the case. An example of an error is below. +`getExecutionString()` function. This function receives a list of `abci.Request` and generates a string where every request +will be replaced with a corresponding terminal. For example, request `r` of type `abci.Request_PrepareProposal` is replaced with the string `prepare_proposal`, the first part of `r`'s string representation. +- Checks if the resulting string with terminals respects the grammar by calling the +`verify()` function. The implementations of both functions are the same; they just use different parsers and lexers. +- Returns true if the execution is valid and an error if that's not the case. An example of an error is below. ``` FAIL: TestCheckABCIGrammar/full02 (8.76s) abci_test.go:24: ABCI grammar verification failed: The error: "Invalid execution: parser was expecting one of [init_chain], got [offer_snapshot] instead." has occurred at height 0. - + Full execution: 0: offer_snapshot apply_snapshot_chunk finalize_block commit 1: finalize_block commit @@ -241,13 +241,13 @@ FAIL: TestCheckABCIGrammar/full02 (8.76s) 3: finalize_block commit ... ``` -The error shown above reports an invalid execution. Moreover, it says why it is considered invalid (`init_chain` was missing) and the height of the error. Notice here that the height in the case of `CleanStart` execution corresponds to the actual consensus height, while for the `Recovery` execution, height 0 represents the first height after the crash. Lastly, after the error, the full execution, one height per line, is printed. This part may be optional and handled with a config flag, but we left it like this for now. +The error shown above reports an invalid execution. Moreover, it says why it is considered invalid (`init_chain` was missing) and the height of the error. Notice here that the height in the case of `CleanStart` execution corresponds to the actual consensus height, while for the `Recovery` execution, height 0 represents the first height after the crash. Lastly, after the error, the full execution, one height per line, is printed. This part may be optional and handled with a config flag, but we left it like this for now. *Note:* The `gogll` parser can return many errors because it returns an error at every point at which the parser fails to parse -a grammar production. Usually, the error of interest is the one that has +a grammar production. Usually, the error of interest is the one that has parsed the largest number of tokens. This is why, by default, we are printing only the last error; however, this can be configured with the `NumberOfErrorsToShow` field of `GrammarChecker`'s config. -Lastly, we present the `verify()` function since this function is the heart of this code. +Lastly, we present the `verify()` function since this function is the heart of this code. ```go func (g *Checker) verify(execution string, isCleanStart bool) []*Error { errors := make([]*Error, 0) @@ -292,27 +292,27 @@ func (g *Checker) verify(execution string, isCleanStart bool) []*Error { ``` -This function first checks if the specific execution represents a valid execution concerning the ABCI grammar. For this, it uses -the auto-generated parser and lexer. If the execution passes this initial test, it checks whether the execution is of a valid type (`CleanStart` or `Recovery`). Namely, it checks whether the execution is of the type specified with the function's second parameter (`isCleanStart`). +This function first checks if the specific execution represents a valid execution concerning the ABCI grammar. For this, it uses +the auto-generated parser and lexer. If the execution passes this initial test, it checks whether the execution is of a valid type (`CleanStart` or `Recovery`). Namely, it checks whether the execution is of the type specified with the function's second parameter (`isCleanStart`). **Changing the grammar** -Any modification to the grammar (`test/e2e/pkg/grammar/abci_grammar.md`) requires generating a new parser and lexer. This is done by +Any modification to the grammar (`test/e2e/pkg/grammar/abci_grammar.md`) requires generating a new parser and lexer. This is done by going to the `test/e2e/` directory and running: -```bash +```bash make grammar-gen -``` +``` Make sure you commit any changes to the auto-generated code together with the changes to the grammar. ### Supporting additional ABCI requests -Here we present all the steps we need to do if we want to support other -ABCI requests in the future: +Here we present all the steps we need to do if we want to support other +ABCI requests in the future: - The application needs to log the new request in the same way as we do now. -- We should include the new request to the grammar and generate a new parser and lexer. +- We should include the new request to the grammar and generate a new parser and lexer. - We should add new requests to the list of supported requests. Namely, we should modify the function `isSupportedByGrammar()` in `test/e2e/pkg/grammar/checker.go` to return `true` for the new type of requests. ## Status @@ -320,13 +320,13 @@ ABCI requests in the future: Implemented. To-do list: -- adding the CI workflow to check if make grammar is executed. +- adding the CI workflow to check if make grammar is executed. - extend this ADR (and implementation) to support ABCI 2.0 (i.e., ABCI calls related to vote extensions) - in the future, we might consider whether the logging (actually, tracing) should be done on the e2e application side, or on CometBFT side, so this infra can be reused for MBT-like activities) ## Consequences ### Positive -- We should be able to check whether CommetBFT respects ABCI 1.0 grammar. +- We should be able to check whether CommetBFT respects ABCI 1.0 grammar. ### Negative ### Neutral diff --git a/docs/architecture/adr-109-reduce-go-api-surface.md b/docs/references/architecture/adr-109-reduce-go-api-surface.md similarity index 99% rename from docs/architecture/adr-109-reduce-go-api-surface.md rename to docs/references/architecture/adr-109-reduce-go-api-surface.md index 29233707ae3..52930c5e7f2 100644 --- a/docs/architecture/adr-109-reduce-go-api-surface.md +++ b/docs/references/architecture/adr-109-reduce-go-api-surface.md @@ -205,7 +205,7 @@ remain publicly exported. All other packages in CometBFT should be moved under releases. [\#1484]: https://github.com/cometbft/cometbft/issues/1484 -[ADR 060]: ./tendermint-core/adr-060-go-api-stability.md +[ADR 060]: tendermint-core/adr-060-go-api-stability.md [Cosmos SDK]: https://github.com/cosmos/cosmos-sdk/ [Cosmos Hub]: https://github.com/cosmos/gaia [IBC Go]: https://github.com/cosmos/ibc-go diff --git a/docs/architecture/adr-110-remote-mempool.md b/docs/references/architecture/adr-110-remote-mempool.md similarity index 99% rename from docs/architecture/adr-110-remote-mempool.md rename to docs/references/architecture/adr-110-remote-mempool.md index 09fa6333c73..93b84480951 100644 --- a/docs/architecture/adr-110-remote-mempool.md +++ b/docs/references/architecture/adr-110-remote-mempool.md @@ -358,5 +358,5 @@ considered for backporting to the `v0.38.x-experimental` branch. [\#1112]: https://github.com/cometbft/cometbft/discussions/1112 [\#1117]: https://github.com/cometbft/cometbft/issues/1117 -[`Mempool`]: ../../mempool/mempool.go +[`Mempool`]: ../../../mempool/mempool.go [RFC 011]: ../rfc/tendermint-core/rfc-011-delete-gas.md diff --git a/docs/architecture/adr-111-nop-mempool.md b/docs/references/architecture/adr-111-nop-mempool.md similarity index 100% rename from docs/architecture/adr-111-nop-mempool.md rename to docs/references/architecture/adr-111-nop-mempool.md diff --git a/docs/architecture/adr-template.md b/docs/references/architecture/adr-template.md similarity index 100% rename from docs/architecture/adr-template.md rename to docs/references/architecture/adr-template.md diff --git a/docs/references/architecture/tendermint-core/README.md b/docs/references/architecture/tendermint-core/README.md new file mode 100644 index 00000000000..89de0c19440 --- /dev/null +++ b/docs/references/architecture/tendermint-core/README.md @@ -0,0 +1,105 @@ +--- +order: 1 +parent: + order: false +--- + +# Tendermint Core Architecture Decision Records (ADR) + +Here we record all high-level architecture decisions in the Tendermint Core +project. All implemented ADRs in this list naturally affect CometBFT, since +CometBFT is a fork of Tendermint Core as of December 2022. + +This list is currently frozen and kept for reference purposes. To add new ADRs, +please do so for CometBFT [here](../). + +## Table of Contents + +### Implemented + +- [ADR-001: Logging](adr-001-logging.md) +- [ADR-002: Event-Subscription](adr-002-event-subscription.md) +- [ADR-003: ABCI-APP-RPC](adr-003-abci-app-rpc.md) +- [ADR-004: Historical-Validators](adr-004-historical-validators.md) +- [ADR-005: Consensus-Params](adr-005-consensus-params.md) +- [ADR-008: Priv-Validator](adr-008-priv-validator.md) +- [ADR-009: ABCI-Design](adr-009-ABCI-design.md) +- [ADR-010: Crypto-Changes](adr-010-crypto-changes.md) +- [ADR-011: Monitoring](adr-011-monitoring.md) +- [ADR-014: Secp-Malleability](adr-014-secp-malleability.md) +- [ADR-015: Crypto-Encoding](adr-015-crypto-encoding.md) +- [ADR-016: Protocol-Versions](adr-016-protocol-versions.md) +- [ADR-017: Chain-Versions](adr-017-chain-versions.md) +- [ADR-018: ABCI-Validators](adr-018-ABCI-Validators.md) +- [ADR-019: Multisigs](adr-019-multisigs.md) +- [ADR-020: Block-Size](adr-020-block-size.md) +- [ADR-021: ABCI-Events](adr-021-abci-events.md) +- [ADR-025: Commit](adr-025-commit.md) +- [ADR-026: General-Merkle-Proof](adr-026-general-merkle-proof.md) +- [ADR-033: Pubsub](adr-033-pubsub.md) +- [ADR-034: Priv-Validator-File-Structure](adr-034-priv-validator-file-structure.md) +- [ADR-043: Blockchain-RiRi-Org](adr-043-blockchain-riri-org.md) +- [ADR-044: Lite-Client-With-Weak-Subjectivity](adr-044-lite-client-with-weak-subjectivity.md) +- [ADR-046: Light-Client-Implementation](adr-046-light-client-implementation.md) +- [ADR-047: Handling-Evidence-From-Light-Client](adr-047-handling-evidence-from-light-client.md) +- [ADR-051: Double-Signing-Risk-Reduction](adr-051-double-signing-risk-reduction.md) +- [ADR-052: Tendermint-Mode](adr-052-tendermint-mode.md) +- [ADR-053: State-Sync-Prototype](adr-053-state-sync-prototype.md) +- [ADR-054: Crypto-Encoding-2](adr-054-crypto-encoding-2.md) +- [ADR-055: Protobuf-Design](adr-055-protobuf-design.md) +- [ADR-056: Light-Client-Amnesia-Attacks](adr-056-light-client-amnesia-attacks.md) +- [ADR-059: Evidence-Composition-and-Lifecycle](adr-059-evidence-composition-and-lifecycle.md) +- [ADR-065: Custom Event Indexing](adr-065-custom-event-indexing.md) +- [ADR-066: E2E-Testing](adr-066-e2e-testing.md) +- [ADR-072: Restore Requests for Comments](adr-072-request-for-comments.md) +- [ADR-076: Combine Spec and Tendermint Repositories](adr-076-combine-spec-repo.md) +- [ADR-077: Configurable Block Retention](adr-077-block-retention.md) +- [ADR-078: Non-zero Genesis](adr-078-nonzero-genesis.md) + +### Accepted + +- [ADR-006: Trust-Metric](adr-006-trust-metric.md) +- [ADR-024: Sign-Bytes](adr-024-sign-bytes.md) +- [ADR-039: Peer-Behaviour](adr-039-peer-behaviour.md) +- [ADR-063: Privval-gRPC](adr-063-privval-grpc.md) +- [ADR-067: Mempool Refactor](adr-067-mempool-refactor.md) +- [ADR-071: Proposer-Based Timestamps](adr-071-proposer-based-timestamps.md) +- [ADR-075: RPC Event Subscription Interface](adr-075-rpc-subscription.md) +- [ADR-079: Ed25519 Verification](adr-079-ed25519-verification.md) +- [ADR-081: Protocol Buffers Management](adr-081-protobuf-mgmt.md) + +### Deprecated + +- [ADR-035: Documentation](adr-035-documentation.md) + +### Rejected + +- [ADR-023: ABCI-Propose-tx](adr-023-ABCI-propose-tx.md) +- [ADR-029: Check-Tx-Consensus](adr-029-check-tx-consensus.md) +- [ADR-058: Event-Hashing](adr-058-event-hashing.md) + +### Proposed + +- [ADR-007: Trust-Metric-Usage](adr-007-trust-metric-usage.md) +- [ADR-012: Peer-Transport](adr-012-peer-transport.md) +- [ADR-013: Symmetric-Crypto](adr-013-symmetric-crypto.md) +- [ADR-022: ABCI-Errors](adr-022-abci-errors.md) +- [ADR-030: Consensus-Refactor](adr-030-consensus-refactor.md) +- [ADR-036: Empty Blocks via ABCI](adr-036-empty-blocks-abci.md) +- [ADR-037: Deliver-Block](adr-037-deliver-block.md) +- [ADR-038: Non-Zero-Start-Height](adr-038-non-zero-start-height.md) +- [ADR-040: Blockchain Reactor Refactor](adr-040-blockchain-reactor-refactor.md) +- [ADR-041: Proposer-Selection-via-ABCI](adr-041-proposer-selection-via-abci.md) +- [ADR-042: State Sync Design](adr-042-state-sync.md) +- [ADR-045: ABCI-Evidence](adr-045-abci-evidence.md) +- [ADR-050: Improved Trusted Peering](adr-050-improved-trusted-peering.md) +- [ADR-057: RPC](adr-057-RPC.md) +- [ADR-060: Go-API-Stability](adr-060-go-api-stability.md) +- [ADR-061: P2P-Refactor-Scope](adr-061-p2p-refactor-scope.md) +- [ADR-062: P2P-Architecture](adr-062-p2p-architecture.md) +- [ADR-064: Batch Verification](adr-064-batch-verification.md) +- [ADR-068: Reverse-Sync](adr-068-reverse-sync.md) +- [ADR-069: Node Initialization](adr-069-flexible-node-initialization.md) +- [ADR-073: Adopt LibP2P](adr-073-libp2p.md) +- [ADR-074: Migrate Timeout Parameters to Consensus Parameters](adr-074-timeout-params.md) +- [ADR-080: Reverse Sync](adr-080-reverse-sync.md) diff --git a/docs/architecture/tendermint-core/adr-001-logging.md b/docs/references/architecture/tendermint-core/adr-001-logging.md similarity index 100% rename from docs/architecture/tendermint-core/adr-001-logging.md rename to docs/references/architecture/tendermint-core/adr-001-logging.md diff --git a/docs/architecture/tendermint-core/adr-002-event-subscription.md b/docs/references/architecture/tendermint-core/adr-002-event-subscription.md similarity index 100% rename from docs/architecture/tendermint-core/adr-002-event-subscription.md rename to docs/references/architecture/tendermint-core/adr-002-event-subscription.md diff --git a/docs/architecture/tendermint-core/adr-003-abci-app-rpc.md b/docs/references/architecture/tendermint-core/adr-003-abci-app-rpc.md similarity index 100% rename from docs/architecture/tendermint-core/adr-003-abci-app-rpc.md rename to docs/references/architecture/tendermint-core/adr-003-abci-app-rpc.md diff --git a/docs/architecture/tendermint-core/adr-004-historical-validators.md b/docs/references/architecture/tendermint-core/adr-004-historical-validators.md similarity index 100% rename from docs/architecture/tendermint-core/adr-004-historical-validators.md rename to docs/references/architecture/tendermint-core/adr-004-historical-validators.md diff --git a/docs/architecture/tendermint-core/adr-005-consensus-params.md b/docs/references/architecture/tendermint-core/adr-005-consensus-params.md similarity index 100% rename from docs/architecture/tendermint-core/adr-005-consensus-params.md rename to docs/references/architecture/tendermint-core/adr-005-consensus-params.md diff --git a/docs/architecture/tendermint-core/adr-006-trust-metric.md b/docs/references/architecture/tendermint-core/adr-006-trust-metric.md similarity index 100% rename from docs/architecture/tendermint-core/adr-006-trust-metric.md rename to docs/references/architecture/tendermint-core/adr-006-trust-metric.md diff --git a/docs/architecture/tendermint-core/adr-007-trust-metric-usage.md b/docs/references/architecture/tendermint-core/adr-007-trust-metric-usage.md similarity index 100% rename from docs/architecture/tendermint-core/adr-007-trust-metric-usage.md rename to docs/references/architecture/tendermint-core/adr-007-trust-metric-usage.md diff --git a/docs/architecture/tendermint-core/adr-008-priv-validator.md b/docs/references/architecture/tendermint-core/adr-008-priv-validator.md similarity index 100% rename from docs/architecture/tendermint-core/adr-008-priv-validator.md rename to docs/references/architecture/tendermint-core/adr-008-priv-validator.md diff --git a/docs/architecture/tendermint-core/adr-009-ABCI-design.md b/docs/references/architecture/tendermint-core/adr-009-ABCI-design.md similarity index 100% rename from docs/architecture/tendermint-core/adr-009-ABCI-design.md rename to docs/references/architecture/tendermint-core/adr-009-ABCI-design.md diff --git a/docs/architecture/tendermint-core/adr-010-crypto-changes.md b/docs/references/architecture/tendermint-core/adr-010-crypto-changes.md similarity index 100% rename from docs/architecture/tendermint-core/adr-010-crypto-changes.md rename to docs/references/architecture/tendermint-core/adr-010-crypto-changes.md diff --git a/docs/architecture/tendermint-core/adr-011-monitoring.md b/docs/references/architecture/tendermint-core/adr-011-monitoring.md similarity index 100% rename from docs/architecture/tendermint-core/adr-011-monitoring.md rename to docs/references/architecture/tendermint-core/adr-011-monitoring.md diff --git a/docs/architecture/tendermint-core/adr-012-peer-transport.md b/docs/references/architecture/tendermint-core/adr-012-peer-transport.md similarity index 100% rename from docs/architecture/tendermint-core/adr-012-peer-transport.md rename to docs/references/architecture/tendermint-core/adr-012-peer-transport.md diff --git a/docs/architecture/tendermint-core/adr-013-symmetric-crypto.md b/docs/references/architecture/tendermint-core/adr-013-symmetric-crypto.md similarity index 100% rename from docs/architecture/tendermint-core/adr-013-symmetric-crypto.md rename to docs/references/architecture/tendermint-core/adr-013-symmetric-crypto.md diff --git a/docs/architecture/tendermint-core/adr-014-secp-malleability.md b/docs/references/architecture/tendermint-core/adr-014-secp-malleability.md similarity index 100% rename from docs/architecture/tendermint-core/adr-014-secp-malleability.md rename to docs/references/architecture/tendermint-core/adr-014-secp-malleability.md diff --git a/docs/architecture/tendermint-core/adr-015-crypto-encoding.md b/docs/references/architecture/tendermint-core/adr-015-crypto-encoding.md similarity index 100% rename from docs/architecture/tendermint-core/adr-015-crypto-encoding.md rename to docs/references/architecture/tendermint-core/adr-015-crypto-encoding.md diff --git a/docs/architecture/tendermint-core/adr-016-protocol-versions.md b/docs/references/architecture/tendermint-core/adr-016-protocol-versions.md similarity index 100% rename from docs/architecture/tendermint-core/adr-016-protocol-versions.md rename to docs/references/architecture/tendermint-core/adr-016-protocol-versions.md diff --git a/docs/architecture/tendermint-core/adr-017-chain-versions.md b/docs/references/architecture/tendermint-core/adr-017-chain-versions.md similarity index 100% rename from docs/architecture/tendermint-core/adr-017-chain-versions.md rename to docs/references/architecture/tendermint-core/adr-017-chain-versions.md diff --git a/docs/architecture/tendermint-core/adr-018-ABCI-Validators.md b/docs/references/architecture/tendermint-core/adr-018-ABCI-Validators.md similarity index 100% rename from docs/architecture/tendermint-core/adr-018-ABCI-Validators.md rename to docs/references/architecture/tendermint-core/adr-018-ABCI-Validators.md diff --git a/docs/architecture/tendermint-core/adr-019-multisigs.md b/docs/references/architecture/tendermint-core/adr-019-multisigs.md similarity index 100% rename from docs/architecture/tendermint-core/adr-019-multisigs.md rename to docs/references/architecture/tendermint-core/adr-019-multisigs.md diff --git a/docs/architecture/tendermint-core/adr-020-block-size.md b/docs/references/architecture/tendermint-core/adr-020-block-size.md similarity index 100% rename from docs/architecture/tendermint-core/adr-020-block-size.md rename to docs/references/architecture/tendermint-core/adr-020-block-size.md diff --git a/docs/architecture/tendermint-core/adr-021-abci-events.md b/docs/references/architecture/tendermint-core/adr-021-abci-events.md similarity index 100% rename from docs/architecture/tendermint-core/adr-021-abci-events.md rename to docs/references/architecture/tendermint-core/adr-021-abci-events.md diff --git a/docs/architecture/tendermint-core/adr-022-abci-errors.md b/docs/references/architecture/tendermint-core/adr-022-abci-errors.md similarity index 100% rename from docs/architecture/tendermint-core/adr-022-abci-errors.md rename to docs/references/architecture/tendermint-core/adr-022-abci-errors.md diff --git a/docs/architecture/tendermint-core/adr-023-ABCI-propose-tx.md b/docs/references/architecture/tendermint-core/adr-023-ABCI-propose-tx.md similarity index 100% rename from docs/architecture/tendermint-core/adr-023-ABCI-propose-tx.md rename to docs/references/architecture/tendermint-core/adr-023-ABCI-propose-tx.md diff --git a/docs/architecture/tendermint-core/adr-024-sign-bytes.md b/docs/references/architecture/tendermint-core/adr-024-sign-bytes.md similarity index 100% rename from docs/architecture/tendermint-core/adr-024-sign-bytes.md rename to docs/references/architecture/tendermint-core/adr-024-sign-bytes.md diff --git a/docs/architecture/tendermint-core/adr-025-commit.md b/docs/references/architecture/tendermint-core/adr-025-commit.md similarity index 100% rename from docs/architecture/tendermint-core/adr-025-commit.md rename to docs/references/architecture/tendermint-core/adr-025-commit.md diff --git a/docs/architecture/tendermint-core/adr-026-general-merkle-proof.md b/docs/references/architecture/tendermint-core/adr-026-general-merkle-proof.md similarity index 100% rename from docs/architecture/tendermint-core/adr-026-general-merkle-proof.md rename to docs/references/architecture/tendermint-core/adr-026-general-merkle-proof.md diff --git a/docs/architecture/tendermint-core/adr-029-check-tx-consensus.md b/docs/references/architecture/tendermint-core/adr-029-check-tx-consensus.md similarity index 100% rename from docs/architecture/tendermint-core/adr-029-check-tx-consensus.md rename to docs/references/architecture/tendermint-core/adr-029-check-tx-consensus.md diff --git a/docs/architecture/tendermint-core/adr-030-consensus-refactor.md b/docs/references/architecture/tendermint-core/adr-030-consensus-refactor.md similarity index 100% rename from docs/architecture/tendermint-core/adr-030-consensus-refactor.md rename to docs/references/architecture/tendermint-core/adr-030-consensus-refactor.md diff --git a/docs/architecture/tendermint-core/adr-033-pubsub.md b/docs/references/architecture/tendermint-core/adr-033-pubsub.md similarity index 100% rename from docs/architecture/tendermint-core/adr-033-pubsub.md rename to docs/references/architecture/tendermint-core/adr-033-pubsub.md diff --git a/docs/architecture/tendermint-core/adr-034-priv-validator-file-structure.md b/docs/references/architecture/tendermint-core/adr-034-priv-validator-file-structure.md similarity index 100% rename from docs/architecture/tendermint-core/adr-034-priv-validator-file-structure.md rename to docs/references/architecture/tendermint-core/adr-034-priv-validator-file-structure.md diff --git a/docs/architecture/tendermint-core/adr-035-documentation.md b/docs/references/architecture/tendermint-core/adr-035-documentation.md similarity index 100% rename from docs/architecture/tendermint-core/adr-035-documentation.md rename to docs/references/architecture/tendermint-core/adr-035-documentation.md diff --git a/docs/architecture/tendermint-core/adr-036-empty-blocks-abci.md b/docs/references/architecture/tendermint-core/adr-036-empty-blocks-abci.md similarity index 100% rename from docs/architecture/tendermint-core/adr-036-empty-blocks-abci.md rename to docs/references/architecture/tendermint-core/adr-036-empty-blocks-abci.md diff --git a/docs/architecture/tendermint-core/adr-037-deliver-block.md b/docs/references/architecture/tendermint-core/adr-037-deliver-block.md similarity index 100% rename from docs/architecture/tendermint-core/adr-037-deliver-block.md rename to docs/references/architecture/tendermint-core/adr-037-deliver-block.md diff --git a/docs/architecture/tendermint-core/adr-038-non-zero-start-height.md b/docs/references/architecture/tendermint-core/adr-038-non-zero-start-height.md similarity index 100% rename from docs/architecture/tendermint-core/adr-038-non-zero-start-height.md rename to docs/references/architecture/tendermint-core/adr-038-non-zero-start-height.md diff --git a/docs/architecture/tendermint-core/adr-039-peer-behaviour.md b/docs/references/architecture/tendermint-core/adr-039-peer-behaviour.md similarity index 100% rename from docs/architecture/tendermint-core/adr-039-peer-behaviour.md rename to docs/references/architecture/tendermint-core/adr-039-peer-behaviour.md diff --git a/docs/architecture/tendermint-core/adr-040-blockchain-reactor-refactor.md b/docs/references/architecture/tendermint-core/adr-040-blockchain-reactor-refactor.md similarity index 100% rename from docs/architecture/tendermint-core/adr-040-blockchain-reactor-refactor.md rename to docs/references/architecture/tendermint-core/adr-040-blockchain-reactor-refactor.md diff --git a/docs/architecture/tendermint-core/adr-041-proposer-selection-via-abci.md b/docs/references/architecture/tendermint-core/adr-041-proposer-selection-via-abci.md similarity index 100% rename from docs/architecture/tendermint-core/adr-041-proposer-selection-via-abci.md rename to docs/references/architecture/tendermint-core/adr-041-proposer-selection-via-abci.md diff --git a/docs/architecture/tendermint-core/adr-042-state-sync.md b/docs/references/architecture/tendermint-core/adr-042-state-sync.md similarity index 100% rename from docs/architecture/tendermint-core/adr-042-state-sync.md rename to docs/references/architecture/tendermint-core/adr-042-state-sync.md diff --git a/docs/architecture/tendermint-core/adr-043-blockchain-riri-org.md b/docs/references/architecture/tendermint-core/adr-043-blockchain-riri-org.md similarity index 100% rename from docs/architecture/tendermint-core/adr-043-blockchain-riri-org.md rename to docs/references/architecture/tendermint-core/adr-043-blockchain-riri-org.md diff --git a/docs/architecture/tendermint-core/adr-044-lite-client-with-weak-subjectivity.md b/docs/references/architecture/tendermint-core/adr-044-lite-client-with-weak-subjectivity.md similarity index 100% rename from docs/architecture/tendermint-core/adr-044-lite-client-with-weak-subjectivity.md rename to docs/references/architecture/tendermint-core/adr-044-lite-client-with-weak-subjectivity.md diff --git a/docs/architecture/tendermint-core/adr-045-abci-evidence.md b/docs/references/architecture/tendermint-core/adr-045-abci-evidence.md similarity index 100% rename from docs/architecture/tendermint-core/adr-045-abci-evidence.md rename to docs/references/architecture/tendermint-core/adr-045-abci-evidence.md diff --git a/docs/architecture/tendermint-core/adr-046-light-client-implementation.md b/docs/references/architecture/tendermint-core/adr-046-light-client-implementation.md similarity index 99% rename from docs/architecture/tendermint-core/adr-046-light-client-implementation.md rename to docs/references/architecture/tendermint-core/adr-046-light-client-implementation.md index 15d77373dc3..3d4351ab7e2 100644 --- a/docs/architecture/tendermint-core/adr-046-light-client-implementation.md +++ b/docs/references/architecture/tendermint-core/adr-046-light-client-implementation.md @@ -143,7 +143,7 @@ the recursive version. There are two major reasons: _Fig. 1: Differences between recursive and non-recursive bisections_ -![Fig. 1](./img/adr-046-fig1.png) +![Fig. 1](img/adr-046-fig1.png) Specification of the non-recursive bisection can be found [here](https://github.com/tendermint/spec/blob/zm_non-recursive-verification/spec/consensus/light-client/non-recursive-verification.md). diff --git a/docs/architecture/tendermint-core/adr-047-handling-evidence-from-light-client.md b/docs/references/architecture/tendermint-core/adr-047-handling-evidence-from-light-client.md similarity index 99% rename from docs/architecture/tendermint-core/adr-047-handling-evidence-from-light-client.md rename to docs/references/architecture/tendermint-core/adr-047-handling-evidence-from-light-client.md index 51b1b2c7f08..dbef4e96ff7 100644 --- a/docs/architecture/tendermint-core/adr-047-handling-evidence-from-light-client.md +++ b/docs/references/architecture/tendermint-core/adr-047-handling-evidence-from-light-client.md @@ -100,7 +100,7 @@ of a different hash then trigger the detection process between the primary and t This begins with verification of the witness's header via skipping verification which is run in tande with locating the Light Bifurcation Point -![](./img/light-client-detector.png) +![](img/light-client-detector.png) This is done with: @@ -137,7 +137,7 @@ divergent header of the primary as it is likely, as seen in the example to the r headers where required in order to verify the divergent one. This trace will be used later (as is also described later in this document). -![](./img/bifurcation-point.png) +![](img/bifurcation-point.png) Now, that an attack has been detected, the light client must form evidence to prove it. There are three types of attacks that either the primary or witness could have done to try fool the light client diff --git a/docs/architecture/tendermint-core/adr-050-improved-trusted-peering.md b/docs/references/architecture/tendermint-core/adr-050-improved-trusted-peering.md similarity index 100% rename from docs/architecture/tendermint-core/adr-050-improved-trusted-peering.md rename to docs/references/architecture/tendermint-core/adr-050-improved-trusted-peering.md diff --git a/docs/architecture/tendermint-core/adr-051-double-signing-risk-reduction.md b/docs/references/architecture/tendermint-core/adr-051-double-signing-risk-reduction.md similarity index 100% rename from docs/architecture/tendermint-core/adr-051-double-signing-risk-reduction.md rename to docs/references/architecture/tendermint-core/adr-051-double-signing-risk-reduction.md diff --git a/docs/architecture/tendermint-core/adr-052-tendermint-mode.md b/docs/references/architecture/tendermint-core/adr-052-tendermint-mode.md similarity index 100% rename from docs/architecture/tendermint-core/adr-052-tendermint-mode.md rename to docs/references/architecture/tendermint-core/adr-052-tendermint-mode.md diff --git a/docs/architecture/tendermint-core/adr-053-state-sync-prototype.md b/docs/references/architecture/tendermint-core/adr-053-state-sync-prototype.md similarity index 98% rename from docs/architecture/tendermint-core/adr-053-state-sync-prototype.md rename to docs/references/architecture/tendermint-core/adr-053-state-sync-prototype.md index 2d8c37ad1cb..84e1e1ad220 100644 --- a/docs/architecture/tendermint-core/adr-053-state-sync-prototype.md +++ b/docs/references/architecture/tendermint-core/adr-053-state-sync-prototype.md @@ -2,7 +2,7 @@ State sync is now [merged](https://github.com/tendermint/tendermint/pull/4705). Up-to-date ABCI documentation is [available](https://github.com/tendermint/spec/pull/90), refer to it rather than this ADR for details. -This ADR outlines the plan for an initial state sync prototype, and is subject to change as we gain feedback and experience. It builds on discussions and findings in [ADR-042](./adr-042-state-sync.md), see that for background information. +This ADR outlines the plan for an initial state sync prototype, and is subject to change as we gain feedback and experience. It builds on discussions and findings in [ADR-042](adr-042-state-sync.md), see that for background information. ## Changelog @@ -30,7 +30,7 @@ This ADR outlines the plan for an initial state sync prototype, and is subject t State sync will allow a new node to receive a snapshot of the application state without downloading blocks or going through consensus. This bootstraps the node significantly faster than the current fast sync system, which replays all historical blocks. -Background discussions and justifications are detailed in [ADR-042](./adr-042-state-sync.md). Its recommendations can be summarized as: +Background discussions and justifications are detailed in [ADR-042](adr-042-state-sync.md). Its recommendations can be summarized as: * The application periodically takes full state snapshots (i.e. eager snapshots). @@ -251,4 +251,4 @@ Implemented ## References -* [ADR-042](./adr-042-state-sync.md) and its references +* [ADR-042](adr-042-state-sync.md) and its references diff --git a/docs/architecture/tendermint-core/adr-054-crypto-encoding-2.md b/docs/references/architecture/tendermint-core/adr-054-crypto-encoding-2.md similarity index 100% rename from docs/architecture/tendermint-core/adr-054-crypto-encoding-2.md rename to docs/references/architecture/tendermint-core/adr-054-crypto-encoding-2.md diff --git a/docs/architecture/tendermint-core/adr-055-protobuf-design.md b/docs/references/architecture/tendermint-core/adr-055-protobuf-design.md similarity index 100% rename from docs/architecture/tendermint-core/adr-055-protobuf-design.md rename to docs/references/architecture/tendermint-core/adr-055-protobuf-design.md diff --git a/docs/architecture/tendermint-core/adr-056-light-client-amnesia-attacks.md b/docs/references/architecture/tendermint-core/adr-056-light-client-amnesia-attacks.md similarity index 99% rename from docs/architecture/tendermint-core/adr-056-light-client-amnesia-attacks.md rename to docs/references/architecture/tendermint-core/adr-056-light-client-amnesia-attacks.md index 7903f6447ab..a4b795c727c 100644 --- a/docs/architecture/tendermint-core/adr-056-light-client-amnesia-attacks.md +++ b/docs/references/architecture/tendermint-core/adr-056-light-client-amnesia-attacks.md @@ -16,7 +16,7 @@ Whilst most created evidence of malicious behavior is self evident such that any The schematic below explains a scenario where an amnesia attack can occur such that two sets of honest nodes, C1 and C2, commit different blocks. -![](./img/tm-amnesia-attack.png) +![](img/tm-amnesia-attack.png) 1. C1 and F send PREVOTE messages for block A. 2. C1 sends PRECOMMIT for round 1 for block A. diff --git a/docs/architecture/tendermint-core/adr-057-RPC.md b/docs/references/architecture/tendermint-core/adr-057-RPC.md similarity index 100% rename from docs/architecture/tendermint-core/adr-057-RPC.md rename to docs/references/architecture/tendermint-core/adr-057-RPC.md diff --git a/docs/architecture/tendermint-core/adr-058-event-hashing.md b/docs/references/architecture/tendermint-core/adr-058-event-hashing.md similarity index 99% rename from docs/architecture/tendermint-core/adr-058-event-hashing.md rename to docs/references/architecture/tendermint-core/adr-058-event-hashing.md index 184b921d5fb..40c80c6c9f7 100644 --- a/docs/architecture/tendermint-core/adr-058-event-hashing.md +++ b/docs/references/architecture/tendermint-core/adr-058-event-hashing.md @@ -109,7 +109,7 @@ and how this ought to ultimately be done by Tendermint.** ## References -- [ADR 021](./adr-021-abci-events.md) +- [ADR 021](adr-021-abci-events.md) - [Indexing transactions](../app-dev/indexing-transactions.md) ## Appendix A. Alternative proposals diff --git a/docs/architecture/tendermint-core/adr-059-evidence-composition-and-lifecycle.md b/docs/references/architecture/tendermint-core/adr-059-evidence-composition-and-lifecycle.md similarity index 99% rename from docs/architecture/tendermint-core/adr-059-evidence-composition-and-lifecycle.md rename to docs/references/architecture/tendermint-core/adr-059-evidence-composition-and-lifecycle.md index d394e4168f7..3030c3d2103 100644 --- a/docs/architecture/tendermint-core/adr-059-evidence-composition-and-lifecycle.md +++ b/docs/references/architecture/tendermint-core/adr-059-evidence-composition-and-lifecycle.md @@ -181,7 +181,7 @@ For `LightClientAttack` - Check that the hashes of the conflicting header and the trusted header are different -- In the case of a forward lunatic attack, where the trusted header height is less than the conflicting header height, the node checks that the time of the trusted header is later than the time of conflicting header. This proves that the conflicting header breaks monotonically increasing time. If the node doesn't have a trusted header with a later time then it is unable to validate the evidence for now. +- In the case of a forward lunatic attack, where the trusted header height is less than the conflicting header height, the node checks that the time of the trusted header is later than the time of conflicting header. This proves that the conflicting header breaks monotonically increasing time. If the node doesn't have a trusted header with a later time then it is unable to validate the evidence for now. - Lastly, for each validator, check the look up table to make sure there already isn't evidence against this validator @@ -271,7 +271,7 @@ The ABCI evidence is then sent via the `BlockExecutor` to the application. To summarize, we can see the lifecycle of evidence as such: -![evidence_lifecycle](./img/evidence_lifecycle.png) +![evidence_lifecycle](img/evidence_lifecycle.png) Evidence is first detected and created in the light client and consensus reactor. It is verified and stored as `EvidenceInfo` and gossiped to the evidence pools in other nodes. The consensus reactor later communicates with the evidence pool to either retrieve evidence to be put into a block, or verify the evidence the consensus reactor has retrieved in a block. Lastly when a block is added to the chain, the block executor sends the committed evidence back to the evidence pool so a pointer to the evidence can be stored in the evidence pool and it can update it's height and time. Finally, it turns the committed evidence into ABCI evidence and through the block executor passes the evidence to the application so the application can handle it. diff --git a/docs/architecture/tendermint-core/adr-060-go-api-stability.md b/docs/references/architecture/tendermint-core/adr-060-go-api-stability.md similarity index 100% rename from docs/architecture/tendermint-core/adr-060-go-api-stability.md rename to docs/references/architecture/tendermint-core/adr-060-go-api-stability.md diff --git a/docs/architecture/tendermint-core/adr-061-p2p-refactor-scope.md b/docs/references/architecture/tendermint-core/adr-061-p2p-refactor-scope.md similarity index 100% rename from docs/architecture/tendermint-core/adr-061-p2p-refactor-scope.md rename to docs/references/architecture/tendermint-core/adr-061-p2p-refactor-scope.md diff --git a/docs/architecture/tendermint-core/adr-062-p2p-architecture.md b/docs/references/architecture/tendermint-core/adr-062-p2p-architecture.md similarity index 100% rename from docs/architecture/tendermint-core/adr-062-p2p-architecture.md rename to docs/references/architecture/tendermint-core/adr-062-p2p-architecture.md diff --git a/docs/architecture/tendermint-core/adr-063-privval-grpc.md b/docs/references/architecture/tendermint-core/adr-063-privval-grpc.md similarity index 100% rename from docs/architecture/tendermint-core/adr-063-privval-grpc.md rename to docs/references/architecture/tendermint-core/adr-063-privval-grpc.md diff --git a/docs/architecture/tendermint-core/adr-064-batch-verification.md b/docs/references/architecture/tendermint-core/adr-064-batch-verification.md similarity index 100% rename from docs/architecture/tendermint-core/adr-064-batch-verification.md rename to docs/references/architecture/tendermint-core/adr-064-batch-verification.md diff --git a/docs/architecture/tendermint-core/adr-065-custom-event-indexing.md b/docs/references/architecture/tendermint-core/adr-065-custom-event-indexing.md similarity index 100% rename from docs/architecture/tendermint-core/adr-065-custom-event-indexing.md rename to docs/references/architecture/tendermint-core/adr-065-custom-event-indexing.md diff --git a/docs/architecture/tendermint-core/adr-066-e2e-testing.md b/docs/references/architecture/tendermint-core/adr-066-e2e-testing.md similarity index 100% rename from docs/architecture/tendermint-core/adr-066-e2e-testing.md rename to docs/references/architecture/tendermint-core/adr-066-e2e-testing.md diff --git a/docs/architecture/tendermint-core/adr-067-mempool-refactor.md b/docs/references/architecture/tendermint-core/adr-067-mempool-refactor.md similarity index 99% rename from docs/architecture/tendermint-core/adr-067-mempool-refactor.md rename to docs/references/architecture/tendermint-core/adr-067-mempool-refactor.md index d217b1df1ef..6fa51da5488 100644 --- a/docs/architecture/tendermint-core/adr-067-mempool-refactor.md +++ b/docs/references/architecture/tendermint-core/adr-067-mempool-refactor.md @@ -71,7 +71,7 @@ can be addressed in an easy and extensible manner in the future. ### Current Design -![mempool](./img/mempool-v0.jpeg) +![mempool](img/mempool-v0.jpeg) At the core of the `v0` mempool reactor is a concurrent linked-list. This is the primary data structure that contains `Tx` objects that have passed `CheckTx`. diff --git a/docs/architecture/tendermint-core/adr-068-reverse-sync.md b/docs/references/architecture/tendermint-core/adr-068-reverse-sync.md similarity index 100% rename from docs/architecture/tendermint-core/adr-068-reverse-sync.md rename to docs/references/architecture/tendermint-core/adr-068-reverse-sync.md diff --git a/docs/architecture/tendermint-core/adr-069-flexible-node-initialization.md b/docs/references/architecture/tendermint-core/adr-069-flexible-node-initialization.md similarity index 97% rename from docs/architecture/tendermint-core/adr-069-flexible-node-initialization.md rename to docs/references/architecture/tendermint-core/adr-069-flexible-node-initialization.md index f6660289854..0860d8daada 100644 --- a/docs/architecture/tendermint-core/adr-069-flexible-node-initialization.md +++ b/docs/references/architecture/tendermint-core/adr-069-flexible-node-initialization.md @@ -12,13 +12,13 @@ Proposed. ## Context -In an effort to support [Go-API-Stability](./adr-060-go-api-stability.md), +In an effort to support [Go-API-Stability](adr-060-go-api-stability.md), during the 0.35 development cycle, we have attempted to reduce the the API surface area by moving most of the interface of the `node` package into unexported functions, as well as moving the reactors to an `internal` package. Having this coincide with the 0.35 release made a lot of sense because these interfaces were _already_ changing as a result of the `p2p` -[refactor](./adr-061-p2p-refactor-scope.md), so it made sense to think a bit +[refactor](adr-061-p2p-refactor-scope.md), so it made sense to think a bit more about how tendermint exposes this API. While the interfaces of the P2P layer and most of the node package are already @@ -265,4 +265,4 @@ described by the following dependency graph makes replacing some of these components more difficult relative to other reactors or components. -![consensus blockchain dependency graph](./img/consensus_blockchain.png) +![consensus blockchain dependency graph](img/consensus_blockchain.png) diff --git a/docs/architecture/tendermint-core/adr-071-proposer-based-timestamps.md b/docs/references/architecture/tendermint-core/adr-071-proposer-based-timestamps.md similarity index 100% rename from docs/architecture/tendermint-core/adr-071-proposer-based-timestamps.md rename to docs/references/architecture/tendermint-core/adr-071-proposer-based-timestamps.md diff --git a/docs/architecture/tendermint-core/adr-072-request-for-comments.md b/docs/references/architecture/tendermint-core/adr-072-request-for-comments.md similarity index 100% rename from docs/architecture/tendermint-core/adr-072-request-for-comments.md rename to docs/references/architecture/tendermint-core/adr-072-request-for-comments.md diff --git a/docs/architecture/tendermint-core/adr-073-libp2p.md b/docs/references/architecture/tendermint-core/adr-073-libp2p.md similarity index 99% rename from docs/architecture/tendermint-core/adr-073-libp2p.md rename to docs/references/architecture/tendermint-core/adr-073-libp2p.md index 080fecbcdf4..549cf64d573 100644 --- a/docs/architecture/tendermint-core/adr-073-libp2p.md +++ b/docs/references/architecture/tendermint-core/adr-073-libp2p.md @@ -230,6 +230,6 @@ the implementation timeline. - [ADR 62: P2P Architecture][adr62] - [P2P Roadmap RFC][rfc] -[adr61]: ./adr-061-p2p-refactor-scope.md -[adr62]: ./adr-062-p2p-architecture.md +[adr61]: adr-061-p2p-refactor-scope.md +[adr62]: adr-062-p2p-architecture.md [rfc]: ../rfc/rfc-000-p2p-roadmap.rst diff --git a/docs/architecture/tendermint-core/adr-074-timeout-params.md b/docs/references/architecture/tendermint-core/adr-074-timeout-params.md similarity index 100% rename from docs/architecture/tendermint-core/adr-074-timeout-params.md rename to docs/references/architecture/tendermint-core/adr-074-timeout-params.md diff --git a/docs/architecture/tendermint-core/adr-075-rpc-subscription.md b/docs/references/architecture/tendermint-core/adr-075-rpc-subscription.md similarity index 99% rename from docs/architecture/tendermint-core/adr-075-rpc-subscription.md rename to docs/references/architecture/tendermint-core/adr-075-rpc-subscription.md index 25f5c3d8a95..ce03fececff 100644 --- a/docs/architecture/tendermint-core/adr-075-rpc-subscription.md +++ b/docs/references/architecture/tendermint-core/adr-075-rpc-subscription.md @@ -516,10 +516,10 @@ crashes and connectivity issues: requires (e.g., reducing to 3/4 of the maximum rather than 1/1). The state of the event log before the publisher acquires the lock: - ![Before publish and pruning](./img/adr-075-log-before.png) + ![Before publish and pruning](img/adr-075-log-before.png) After the publisher has added a new item and pruned old ones: - ![After publish and pruning](./img/adr-075-log-after.png) + ![After publish and pruning](img/adr-075-log-after.png) ### Migration Plan diff --git a/docs/architecture/tendermint-core/adr-076-combine-spec-repo.md b/docs/references/architecture/tendermint-core/adr-076-combine-spec-repo.md similarity index 100% rename from docs/architecture/tendermint-core/adr-076-combine-spec-repo.md rename to docs/references/architecture/tendermint-core/adr-076-combine-spec-repo.md diff --git a/docs/architecture/tendermint-core/adr-077-block-retention.md b/docs/references/architecture/tendermint-core/adr-077-block-retention.md similarity index 100% rename from docs/architecture/tendermint-core/adr-077-block-retention.md rename to docs/references/architecture/tendermint-core/adr-077-block-retention.md diff --git a/docs/architecture/tendermint-core/adr-078-nonzero-genesis.md b/docs/references/architecture/tendermint-core/adr-078-nonzero-genesis.md similarity index 100% rename from docs/architecture/tendermint-core/adr-078-nonzero-genesis.md rename to docs/references/architecture/tendermint-core/adr-078-nonzero-genesis.md diff --git a/docs/architecture/tendermint-core/adr-079-ed25519-verification.md b/docs/references/architecture/tendermint-core/adr-079-ed25519-verification.md similarity index 100% rename from docs/architecture/tendermint-core/adr-079-ed25519-verification.md rename to docs/references/architecture/tendermint-core/adr-079-ed25519-verification.md diff --git a/docs/architecture/tendermint-core/adr-080-reverse-sync.md b/docs/references/architecture/tendermint-core/adr-080-reverse-sync.md similarity index 100% rename from docs/architecture/tendermint-core/adr-080-reverse-sync.md rename to docs/references/architecture/tendermint-core/adr-080-reverse-sync.md diff --git a/docs/architecture/tendermint-core/adr-081-protobuf-mgmt.md b/docs/references/architecture/tendermint-core/adr-081-protobuf-mgmt.md similarity index 100% rename from docs/architecture/tendermint-core/adr-081-protobuf-mgmt.md rename to docs/references/architecture/tendermint-core/adr-081-protobuf-mgmt.md diff --git a/docs/architecture/tendermint-core/img/adr-046-fig1.png b/docs/references/architecture/tendermint-core/img/adr-046-fig1.png similarity index 100% rename from docs/architecture/tendermint-core/img/adr-046-fig1.png rename to docs/references/architecture/tendermint-core/img/adr-046-fig1.png diff --git a/docs/architecture/tendermint-core/img/adr-062-architecture.svg b/docs/references/architecture/tendermint-core/img/adr-062-architecture.svg similarity index 100% rename from docs/architecture/tendermint-core/img/adr-062-architecture.svg rename to docs/references/architecture/tendermint-core/img/adr-062-architecture.svg diff --git a/docs/architecture/tendermint-core/img/adr-075-log-after.png b/docs/references/architecture/tendermint-core/img/adr-075-log-after.png similarity index 100% rename from docs/architecture/tendermint-core/img/adr-075-log-after.png rename to docs/references/architecture/tendermint-core/img/adr-075-log-after.png diff --git a/docs/architecture/tendermint-core/img/adr-075-log-before.png b/docs/references/architecture/tendermint-core/img/adr-075-log-before.png similarity index 100% rename from docs/architecture/tendermint-core/img/adr-075-log-before.png rename to docs/references/architecture/tendermint-core/img/adr-075-log-before.png diff --git a/docs/architecture/tendermint-core/img/bc-reactor-refactor.png b/docs/references/architecture/tendermint-core/img/bc-reactor-refactor.png similarity index 100% rename from docs/architecture/tendermint-core/img/bc-reactor-refactor.png rename to docs/references/architecture/tendermint-core/img/bc-reactor-refactor.png diff --git a/docs/architecture/tendermint-core/img/bc-reactor.png b/docs/references/architecture/tendermint-core/img/bc-reactor.png similarity index 100% rename from docs/architecture/tendermint-core/img/bc-reactor.png rename to docs/references/architecture/tendermint-core/img/bc-reactor.png diff --git a/docs/architecture/tendermint-core/img/bifurcation-point.png b/docs/references/architecture/tendermint-core/img/bifurcation-point.png similarity index 100% rename from docs/architecture/tendermint-core/img/bifurcation-point.png rename to docs/references/architecture/tendermint-core/img/bifurcation-point.png diff --git a/docs/architecture/tendermint-core/img/block-retention.png b/docs/references/architecture/tendermint-core/img/block-retention.png similarity index 100% rename from docs/architecture/tendermint-core/img/block-retention.png rename to docs/references/architecture/tendermint-core/img/block-retention.png diff --git a/docs/architecture/tendermint-core/img/blockchain-reactor-v1.png b/docs/references/architecture/tendermint-core/img/blockchain-reactor-v1.png similarity index 100% rename from docs/architecture/tendermint-core/img/blockchain-reactor-v1.png rename to docs/references/architecture/tendermint-core/img/blockchain-reactor-v1.png diff --git a/docs/architecture/tendermint-core/img/blockchain-reactor-v2.png b/docs/references/architecture/tendermint-core/img/blockchain-reactor-v2.png similarity index 100% rename from docs/architecture/tendermint-core/img/blockchain-reactor-v2.png rename to docs/references/architecture/tendermint-core/img/blockchain-reactor-v2.png diff --git a/docs/architecture/tendermint-core/img/blockchain-v2-channels.png b/docs/references/architecture/tendermint-core/img/blockchain-v2-channels.png similarity index 100% rename from docs/architecture/tendermint-core/img/blockchain-v2-channels.png rename to docs/references/architecture/tendermint-core/img/blockchain-v2-channels.png diff --git a/docs/architecture/tendermint-core/img/consensus_blockchain.png b/docs/references/architecture/tendermint-core/img/consensus_blockchain.png similarity index 100% rename from docs/architecture/tendermint-core/img/consensus_blockchain.png rename to docs/references/architecture/tendermint-core/img/consensus_blockchain.png diff --git a/docs/architecture/tendermint-core/img/evidence_lifecycle.png b/docs/references/architecture/tendermint-core/img/evidence_lifecycle.png similarity index 100% rename from docs/architecture/tendermint-core/img/evidence_lifecycle.png rename to docs/references/architecture/tendermint-core/img/evidence_lifecycle.png diff --git a/docs/architecture/tendermint-core/img/formula1.png b/docs/references/architecture/tendermint-core/img/formula1.png similarity index 100% rename from docs/architecture/tendermint-core/img/formula1.png rename to docs/references/architecture/tendermint-core/img/formula1.png diff --git a/docs/architecture/tendermint-core/img/formula2.png b/docs/references/architecture/tendermint-core/img/formula2.png similarity index 100% rename from docs/architecture/tendermint-core/img/formula2.png rename to docs/references/architecture/tendermint-core/img/formula2.png diff --git a/docs/architecture/tendermint-core/img/light-client-detector.png b/docs/references/architecture/tendermint-core/img/light-client-detector.png similarity index 100% rename from docs/architecture/tendermint-core/img/light-client-detector.png rename to docs/references/architecture/tendermint-core/img/light-client-detector.png diff --git a/docs/architecture/tendermint-core/img/mempool-v0.jpeg b/docs/references/architecture/tendermint-core/img/mempool-v0.jpeg similarity index 100% rename from docs/architecture/tendermint-core/img/mempool-v0.jpeg rename to docs/references/architecture/tendermint-core/img/mempool-v0.jpeg diff --git a/docs/architecture/tendermint-core/img/pbts-message.png b/docs/references/architecture/tendermint-core/img/pbts-message.png similarity index 100% rename from docs/architecture/tendermint-core/img/pbts-message.png rename to docs/references/architecture/tendermint-core/img/pbts-message.png diff --git a/docs/architecture/tendermint-core/img/state-sync.png b/docs/references/architecture/tendermint-core/img/state-sync.png similarity index 100% rename from docs/architecture/tendermint-core/img/state-sync.png rename to docs/references/architecture/tendermint-core/img/state-sync.png diff --git a/docs/architecture/tendermint-core/img/tags1.png b/docs/references/architecture/tendermint-core/img/tags1.png similarity index 100% rename from docs/architecture/tendermint-core/img/tags1.png rename to docs/references/architecture/tendermint-core/img/tags1.png diff --git a/docs/architecture/tendermint-core/img/tm-amnesia-attack.png b/docs/references/architecture/tendermint-core/img/tm-amnesia-attack.png similarity index 100% rename from docs/architecture/tendermint-core/img/tm-amnesia-attack.png rename to docs/references/architecture/tendermint-core/img/tm-amnesia-attack.png diff --git a/docs/qa/CometBFT-QA-34.md b/docs/references/qa/CometBFT-QA-34.md similarity index 100% rename from docs/qa/CometBFT-QA-34.md rename to docs/references/qa/CometBFT-QA-34.md diff --git a/docs/qa/CometBFT-QA-37.md b/docs/references/qa/CometBFT-QA-37.md similarity index 100% rename from docs/qa/CometBFT-QA-37.md rename to docs/references/qa/CometBFT-QA-37.md diff --git a/docs/qa/CometBFT-QA-38.md b/docs/references/qa/CometBFT-QA-38.md similarity index 99% rename from docs/qa/CometBFT-QA-38.md rename to docs/references/qa/CometBFT-QA-38.md index 591cce884e6..77f4022651a 100644 --- a/docs/qa/CometBFT-QA-38.md +++ b/docs/references/qa/CometBFT-QA-38.md @@ -37,7 +37,7 @@ load on which the system begins to show a degraded performance. Then we run the experiments with the system subjected to a load slightly under the saturation point. The method to identify the saturation point is explained [here](CometBFT-QA-34.md#saturation-point) and its application to the baseline -is described [here](TMCore-QA-37.md#finding-the-saturation-point). +is described [here](TMCore-QA-37.md#finding-the-saturation-point). The following table summarizes the results for the different experiments (extracted from @@ -56,7 +56,7 @@ second. We can observe in the table that the system is saturated beyond the diagonal defined by the entries `c=1,r=400` and `c=2,r=200`. Entries in the diagonal have the same amount of transaction load, so we can consider them equivalent. For the -chosen diagonal, the expected number of processed transactions is `1 * 400 tx/s * 89 s = 35600`. +chosen diagonal, the expected number of processed transactions is `1 * 400 tx/s * 89 s = 35600`. (Note that we use 89 out of 90 seconds of the experiment because the last transaction batch coincides with the end of the experiment and is thus not sent.) The experiments in the diagonal below expect double that number, that is, `1 * 800 tx/s * 89 s = 71200`, but the @@ -91,7 +91,7 @@ configuration `c=1,r=400`. ![latency-1-400](img38/200nodes/e_de676ecf-038e-443f-a26a-27915f29e312.png). For reference, the following figure shows the latencies of one of the -experiments for `c=2,r=200` in the baseline. +experiments for `c=2,r=200` in the baseline. ![latency-2-200-37](img37/200nodes_cmt037/e_75cb89a8-f876-4698-82f3-8aaab0b361af.png) @@ -327,7 +327,7 @@ This is the baseline plot, for comparison. The plotted values and their evolution are comparable in both plots. -For further details on these plots, see the [this section](./TMCore-QA-34.md#peers-1). +For further details on these plots, see the [this section](TMCore-QA-34.md#peers-1). #### Memory Resident Set Size diff --git a/docs/qa/README.md b/docs/references/qa/README.md similarity index 94% rename from docs/qa/README.md rename to docs/references/qa/README.md index d019d45808d..2b555f04bd2 100644 --- a/docs/qa/README.md +++ b/docs/references/qa/README.md @@ -14,7 +14,7 @@ This directory is to live in multiple branches. On each release branch, the contents of this directory reflect the status of the process at the time the Quality Assurance process was applied for that release. -File [method](./method.md) keeps track of the process followed to obtain the results +File [method](method.md) keeps track of the process followed to obtain the results used to decide if a release is passing the Quality Assurance process. The results obtained in each release are stored in their own directory. The following releases have undergone the Quality Assurance process, and the corresponding reports include detailed information on tests and comparison with the baseline. diff --git a/docs/qa/TMCore-QA-34.md b/docs/references/qa/TMCore-QA-34.md similarity index 100% rename from docs/qa/TMCore-QA-34.md rename to docs/references/qa/TMCore-QA-34.md diff --git a/docs/qa/TMCore-QA-37.md b/docs/references/qa/TMCore-QA-37.md similarity index 100% rename from docs/qa/TMCore-QA-37.md rename to docs/references/qa/TMCore-QA-37.md diff --git a/docs/qa/img34/baseline/avg_cpu.png b/docs/references/qa/img34/baseline/avg_cpu.png similarity index 100% rename from docs/qa/img34/baseline/avg_cpu.png rename to docs/references/qa/img34/baseline/avg_cpu.png diff --git a/docs/qa/img34/baseline/avg_memory.png b/docs/references/qa/img34/baseline/avg_memory.png similarity index 100% rename from docs/qa/img34/baseline/avg_memory.png rename to docs/references/qa/img34/baseline/avg_memory.png diff --git a/docs/qa/img34/baseline/avg_mempool_size.png b/docs/references/qa/img34/baseline/avg_mempool_size.png similarity index 100% rename from docs/qa/img34/baseline/avg_mempool_size.png rename to docs/references/qa/img34/baseline/avg_mempool_size.png diff --git a/docs/qa/img34/baseline/block_rate_regular.png b/docs/references/qa/img34/baseline/block_rate_regular.png similarity index 100% rename from docs/qa/img34/baseline/block_rate_regular.png rename to docs/references/qa/img34/baseline/block_rate_regular.png diff --git a/docs/qa/img34/baseline/cpu.png b/docs/references/qa/img34/baseline/cpu.png similarity index 100% rename from docs/qa/img34/baseline/cpu.png rename to docs/references/qa/img34/baseline/cpu.png diff --git a/docs/qa/img34/baseline/memory.png b/docs/references/qa/img34/baseline/memory.png similarity index 100% rename from docs/qa/img34/baseline/memory.png rename to docs/references/qa/img34/baseline/memory.png diff --git a/docs/qa/img34/baseline/mempool_size.png b/docs/references/qa/img34/baseline/mempool_size.png similarity index 100% rename from docs/qa/img34/baseline/mempool_size.png rename to docs/references/qa/img34/baseline/mempool_size.png diff --git a/docs/qa/img34/baseline/peers.png b/docs/references/qa/img34/baseline/peers.png similarity index 100% rename from docs/qa/img34/baseline/peers.png rename to docs/references/qa/img34/baseline/peers.png diff --git a/docs/qa/img34/baseline/rounds.png b/docs/references/qa/img34/baseline/rounds.png similarity index 100% rename from docs/qa/img34/baseline/rounds.png rename to docs/references/qa/img34/baseline/rounds.png diff --git a/docs/qa/img34/baseline/total_txs_rate_regular.png b/docs/references/qa/img34/baseline/total_txs_rate_regular.png similarity index 100% rename from docs/qa/img34/baseline/total_txs_rate_regular.png rename to docs/references/qa/img34/baseline/total_txs_rate_regular.png diff --git a/docs/qa/img34/cmt1tm1/all_experiments.png b/docs/references/qa/img34/cmt1tm1/all_experiments.png similarity index 100% rename from docs/qa/img34/cmt1tm1/all_experiments.png rename to docs/references/qa/img34/cmt1tm1/all_experiments.png diff --git a/docs/qa/img34/cmt1tm1/avg_cpu.png b/docs/references/qa/img34/cmt1tm1/avg_cpu.png similarity index 100% rename from docs/qa/img34/cmt1tm1/avg_cpu.png rename to docs/references/qa/img34/cmt1tm1/avg_cpu.png diff --git a/docs/qa/img34/cmt1tm1/avg_memory.png b/docs/references/qa/img34/cmt1tm1/avg_memory.png similarity index 100% rename from docs/qa/img34/cmt1tm1/avg_memory.png rename to docs/references/qa/img34/cmt1tm1/avg_memory.png diff --git a/docs/qa/img34/cmt1tm1/avg_mempool_size.png b/docs/references/qa/img34/cmt1tm1/avg_mempool_size.png similarity index 100% rename from docs/qa/img34/cmt1tm1/avg_mempool_size.png rename to docs/references/qa/img34/cmt1tm1/avg_mempool_size.png diff --git a/docs/qa/img34/cmt1tm1/block_rate_regular.png b/docs/references/qa/img34/cmt1tm1/block_rate_regular.png similarity index 100% rename from docs/qa/img34/cmt1tm1/block_rate_regular.png rename to docs/references/qa/img34/cmt1tm1/block_rate_regular.png diff --git a/docs/qa/img34/cmt1tm1/cpu.png b/docs/references/qa/img34/cmt1tm1/cpu.png similarity index 100% rename from docs/qa/img34/cmt1tm1/cpu.png rename to docs/references/qa/img34/cmt1tm1/cpu.png diff --git a/docs/qa/img34/cmt1tm1/memory.png b/docs/references/qa/img34/cmt1tm1/memory.png similarity index 100% rename from docs/qa/img34/cmt1tm1/memory.png rename to docs/references/qa/img34/cmt1tm1/memory.png diff --git a/docs/qa/img34/cmt1tm1/mempool_size.png b/docs/references/qa/img34/cmt1tm1/mempool_size.png similarity index 100% rename from docs/qa/img34/cmt1tm1/mempool_size.png rename to docs/references/qa/img34/cmt1tm1/mempool_size.png diff --git a/docs/qa/img34/cmt1tm1/peers.png b/docs/references/qa/img34/cmt1tm1/peers.png similarity index 100% rename from docs/qa/img34/cmt1tm1/peers.png rename to docs/references/qa/img34/cmt1tm1/peers.png diff --git a/docs/qa/img34/cmt1tm1/rounds.png b/docs/references/qa/img34/cmt1tm1/rounds.png similarity index 100% rename from docs/qa/img34/cmt1tm1/rounds.png rename to docs/references/qa/img34/cmt1tm1/rounds.png diff --git a/docs/qa/img34/cmt1tm1/total_txs_rate_regular.png b/docs/references/qa/img34/cmt1tm1/total_txs_rate_regular.png similarity index 100% rename from docs/qa/img34/cmt1tm1/total_txs_rate_regular.png rename to docs/references/qa/img34/cmt1tm1/total_txs_rate_regular.png diff --git a/docs/qa/img34/cmt2tm1/all_experiments.png b/docs/references/qa/img34/cmt2tm1/all_experiments.png similarity index 100% rename from docs/qa/img34/cmt2tm1/all_experiments.png rename to docs/references/qa/img34/cmt2tm1/all_experiments.png diff --git a/docs/qa/img34/cmt2tm1/avg_cpu.png b/docs/references/qa/img34/cmt2tm1/avg_cpu.png similarity index 100% rename from docs/qa/img34/cmt2tm1/avg_cpu.png rename to docs/references/qa/img34/cmt2tm1/avg_cpu.png diff --git a/docs/qa/img34/cmt2tm1/avg_memory.png b/docs/references/qa/img34/cmt2tm1/avg_memory.png similarity index 100% rename from docs/qa/img34/cmt2tm1/avg_memory.png rename to docs/references/qa/img34/cmt2tm1/avg_memory.png diff --git a/docs/qa/img34/cmt2tm1/avg_mempool_size.png b/docs/references/qa/img34/cmt2tm1/avg_mempool_size.png similarity index 100% rename from docs/qa/img34/cmt2tm1/avg_mempool_size.png rename to docs/references/qa/img34/cmt2tm1/avg_mempool_size.png diff --git a/docs/qa/img34/cmt2tm1/block_rate_regular.png b/docs/references/qa/img34/cmt2tm1/block_rate_regular.png similarity index 100% rename from docs/qa/img34/cmt2tm1/block_rate_regular.png rename to docs/references/qa/img34/cmt2tm1/block_rate_regular.png diff --git a/docs/qa/img34/cmt2tm1/cpu.png b/docs/references/qa/img34/cmt2tm1/cpu.png similarity index 100% rename from docs/qa/img34/cmt2tm1/cpu.png rename to docs/references/qa/img34/cmt2tm1/cpu.png diff --git a/docs/qa/img34/cmt2tm1/memory.png b/docs/references/qa/img34/cmt2tm1/memory.png similarity index 100% rename from docs/qa/img34/cmt2tm1/memory.png rename to docs/references/qa/img34/cmt2tm1/memory.png diff --git a/docs/qa/img34/cmt2tm1/mempool_size.png b/docs/references/qa/img34/cmt2tm1/mempool_size.png similarity index 100% rename from docs/qa/img34/cmt2tm1/mempool_size.png rename to docs/references/qa/img34/cmt2tm1/mempool_size.png diff --git a/docs/qa/img34/cmt2tm1/peers.png b/docs/references/qa/img34/cmt2tm1/peers.png similarity index 100% rename from docs/qa/img34/cmt2tm1/peers.png rename to docs/references/qa/img34/cmt2tm1/peers.png diff --git a/docs/qa/img34/cmt2tm1/rounds.png b/docs/references/qa/img34/cmt2tm1/rounds.png similarity index 100% rename from docs/qa/img34/cmt2tm1/rounds.png rename to docs/references/qa/img34/cmt2tm1/rounds.png diff --git a/docs/qa/img34/cmt2tm1/total_txs_rate_regular.png b/docs/references/qa/img34/cmt2tm1/total_txs_rate_regular.png similarity index 100% rename from docs/qa/img34/cmt2tm1/total_txs_rate_regular.png rename to docs/references/qa/img34/cmt2tm1/total_txs_rate_regular.png diff --git a/docs/qa/img34/homogeneous/all_experiments.png b/docs/references/qa/img34/homogeneous/all_experiments.png similarity index 100% rename from docs/qa/img34/homogeneous/all_experiments.png rename to docs/references/qa/img34/homogeneous/all_experiments.png diff --git a/docs/qa/img34/homogeneous/avg_cpu.png b/docs/references/qa/img34/homogeneous/avg_cpu.png similarity index 100% rename from docs/qa/img34/homogeneous/avg_cpu.png rename to docs/references/qa/img34/homogeneous/avg_cpu.png diff --git a/docs/qa/img34/homogeneous/avg_memory.png b/docs/references/qa/img34/homogeneous/avg_memory.png similarity index 100% rename from docs/qa/img34/homogeneous/avg_memory.png rename to docs/references/qa/img34/homogeneous/avg_memory.png diff --git a/docs/qa/img34/homogeneous/avg_mempool_size.png b/docs/references/qa/img34/homogeneous/avg_mempool_size.png similarity index 100% rename from docs/qa/img34/homogeneous/avg_mempool_size.png rename to docs/references/qa/img34/homogeneous/avg_mempool_size.png diff --git a/docs/qa/img34/homogeneous/block_rate_regular.png b/docs/references/qa/img34/homogeneous/block_rate_regular.png similarity index 100% rename from docs/qa/img34/homogeneous/block_rate_regular.png rename to docs/references/qa/img34/homogeneous/block_rate_regular.png diff --git a/docs/qa/img34/homogeneous/cpu.png b/docs/references/qa/img34/homogeneous/cpu.png similarity index 100% rename from docs/qa/img34/homogeneous/cpu.png rename to docs/references/qa/img34/homogeneous/cpu.png diff --git a/docs/qa/img34/homogeneous/memory.png b/docs/references/qa/img34/homogeneous/memory.png similarity index 100% rename from docs/qa/img34/homogeneous/memory.png rename to docs/references/qa/img34/homogeneous/memory.png diff --git a/docs/qa/img34/homogeneous/mempool_size.png b/docs/references/qa/img34/homogeneous/mempool_size.png similarity index 100% rename from docs/qa/img34/homogeneous/mempool_size.png rename to docs/references/qa/img34/homogeneous/mempool_size.png diff --git a/docs/qa/img34/homogeneous/peers.png b/docs/references/qa/img34/homogeneous/peers.png similarity index 100% rename from docs/qa/img34/homogeneous/peers.png rename to docs/references/qa/img34/homogeneous/peers.png diff --git a/docs/qa/img34/homogeneous/rounds.png b/docs/references/qa/img34/homogeneous/rounds.png similarity index 100% rename from docs/qa/img34/homogeneous/rounds.png rename to docs/references/qa/img34/homogeneous/rounds.png diff --git a/docs/qa/img34/homogeneous/total_txs_rate_regular.png b/docs/references/qa/img34/homogeneous/total_txs_rate_regular.png similarity index 100% rename from docs/qa/img34/homogeneous/total_txs_rate_regular.png rename to docs/references/qa/img34/homogeneous/total_txs_rate_regular.png diff --git a/docs/qa/img34/v034_200node_latencies.png b/docs/references/qa/img34/v034_200node_latencies.png similarity index 100% rename from docs/qa/img34/v034_200node_latencies.png rename to docs/references/qa/img34/v034_200node_latencies.png diff --git a/docs/qa/img34/v034_200node_latencies_zoomed.png b/docs/references/qa/img34/v034_200node_latencies_zoomed.png similarity index 100% rename from docs/qa/img34/v034_200node_latencies_zoomed.png rename to docs/references/qa/img34/v034_200node_latencies_zoomed.png diff --git a/docs/qa/img34/v034_200node_tm2cmt1/all_experiments.png b/docs/references/qa/img34/v034_200node_tm2cmt1/all_experiments.png similarity index 100% rename from docs/qa/img34/v034_200node_tm2cmt1/all_experiments.png rename to docs/references/qa/img34/v034_200node_tm2cmt1/all_experiments.png diff --git a/docs/qa/img34/v034_200node_tm2cmt1/avg_cpu.png b/docs/references/qa/img34/v034_200node_tm2cmt1/avg_cpu.png similarity index 100% rename from docs/qa/img34/v034_200node_tm2cmt1/avg_cpu.png rename to docs/references/qa/img34/v034_200node_tm2cmt1/avg_cpu.png diff --git a/docs/qa/img34/v034_200node_tm2cmt1/avg_memory.png b/docs/references/qa/img34/v034_200node_tm2cmt1/avg_memory.png similarity index 100% rename from docs/qa/img34/v034_200node_tm2cmt1/avg_memory.png rename to docs/references/qa/img34/v034_200node_tm2cmt1/avg_memory.png diff --git a/docs/qa/img34/v034_200node_tm2cmt1/avg_mempool_size.png b/docs/references/qa/img34/v034_200node_tm2cmt1/avg_mempool_size.png similarity index 100% rename from docs/qa/img34/v034_200node_tm2cmt1/avg_mempool_size.png rename to docs/references/qa/img34/v034_200node_tm2cmt1/avg_mempool_size.png diff --git a/docs/qa/img34/v034_200node_tm2cmt1/block_rate_regular.png b/docs/references/qa/img34/v034_200node_tm2cmt1/block_rate_regular.png similarity index 100% rename from docs/qa/img34/v034_200node_tm2cmt1/block_rate_regular.png rename to docs/references/qa/img34/v034_200node_tm2cmt1/block_rate_regular.png diff --git a/docs/qa/img34/v034_200node_tm2cmt1/c2r200_merged.png b/docs/references/qa/img34/v034_200node_tm2cmt1/c2r200_merged.png similarity index 100% rename from docs/qa/img34/v034_200node_tm2cmt1/c2r200_merged.png rename to docs/references/qa/img34/v034_200node_tm2cmt1/c2r200_merged.png diff --git a/docs/qa/img34/v034_200node_tm2cmt1/cpu.png b/docs/references/qa/img34/v034_200node_tm2cmt1/cpu.png similarity index 100% rename from docs/qa/img34/v034_200node_tm2cmt1/cpu.png rename to docs/references/qa/img34/v034_200node_tm2cmt1/cpu.png diff --git a/docs/qa/img34/v034_200node_tm2cmt1/memory.png b/docs/references/qa/img34/v034_200node_tm2cmt1/memory.png similarity index 100% rename from docs/qa/img34/v034_200node_tm2cmt1/memory.png rename to docs/references/qa/img34/v034_200node_tm2cmt1/memory.png diff --git a/docs/qa/img34/v034_200node_tm2cmt1/mempool_size.png b/docs/references/qa/img34/v034_200node_tm2cmt1/mempool_size.png similarity index 100% rename from docs/qa/img34/v034_200node_tm2cmt1/mempool_size.png rename to docs/references/qa/img34/v034_200node_tm2cmt1/mempool_size.png diff --git a/docs/qa/img34/v034_200node_tm2cmt1/peers.png b/docs/references/qa/img34/v034_200node_tm2cmt1/peers.png similarity index 100% rename from docs/qa/img34/v034_200node_tm2cmt1/peers.png rename to docs/references/qa/img34/v034_200node_tm2cmt1/peers.png diff --git a/docs/qa/img34/v034_200node_tm2cmt1/rounds.png b/docs/references/qa/img34/v034_200node_tm2cmt1/rounds.png similarity index 100% rename from docs/qa/img34/v034_200node_tm2cmt1/rounds.png rename to docs/references/qa/img34/v034_200node_tm2cmt1/rounds.png diff --git a/docs/qa/img34/v034_200node_tm2cmt1/total_txs_rate_regular.png b/docs/references/qa/img34/v034_200node_tm2cmt1/total_txs_rate_regular.png similarity index 100% rename from docs/qa/img34/v034_200node_tm2cmt1/total_txs_rate_regular.png rename to docs/references/qa/img34/v034_200node_tm2cmt1/total_txs_rate_regular.png diff --git a/docs/qa/img34/v034_latency_throughput.png b/docs/references/qa/img34/v034_latency_throughput.png similarity index 100% rename from docs/qa/img34/v034_latency_throughput.png rename to docs/references/qa/img34/v034_latency_throughput.png diff --git a/docs/qa/img34/v034_r200c2_heights.png b/docs/references/qa/img34/v034_r200c2_heights.png similarity index 100% rename from docs/qa/img34/v034_r200c2_heights.png rename to docs/references/qa/img34/v034_r200c2_heights.png diff --git a/docs/qa/img34/v034_r200c2_load-runner.png b/docs/references/qa/img34/v034_r200c2_load-runner.png similarity index 100% rename from docs/qa/img34/v034_r200c2_load-runner.png rename to docs/references/qa/img34/v034_r200c2_load-runner.png diff --git a/docs/qa/img34/v034_r200c2_load1.png b/docs/references/qa/img34/v034_r200c2_load1.png similarity index 100% rename from docs/qa/img34/v034_r200c2_load1.png rename to docs/references/qa/img34/v034_r200c2_load1.png diff --git a/docs/qa/img34/v034_r200c2_mempool_size.png b/docs/references/qa/img34/v034_r200c2_mempool_size.png similarity index 100% rename from docs/qa/img34/v034_r200c2_mempool_size.png rename to docs/references/qa/img34/v034_r200c2_mempool_size.png diff --git a/docs/qa/img34/v034_r200c2_mempool_size_avg.png b/docs/references/qa/img34/v034_r200c2_mempool_size_avg.png similarity index 100% rename from docs/qa/img34/v034_r200c2_mempool_size_avg.png rename to docs/references/qa/img34/v034_r200c2_mempool_size_avg.png diff --git a/docs/qa/img34/v034_r200c2_peers.png b/docs/references/qa/img34/v034_r200c2_peers.png similarity index 100% rename from docs/qa/img34/v034_r200c2_peers.png rename to docs/references/qa/img34/v034_r200c2_peers.png diff --git a/docs/qa/img34/v034_r200c2_rounds.png b/docs/references/qa/img34/v034_r200c2_rounds.png similarity index 100% rename from docs/qa/img34/v034_r200c2_rounds.png rename to docs/references/qa/img34/v034_r200c2_rounds.png diff --git a/docs/qa/img34/v034_r200c2_rss.png b/docs/references/qa/img34/v034_r200c2_rss.png similarity index 100% rename from docs/qa/img34/v034_r200c2_rss.png rename to docs/references/qa/img34/v034_r200c2_rss.png diff --git a/docs/qa/img34/v034_r200c2_rss_avg.png b/docs/references/qa/img34/v034_r200c2_rss_avg.png similarity index 100% rename from docs/qa/img34/v034_r200c2_rss_avg.png rename to docs/references/qa/img34/v034_r200c2_rss_avg.png diff --git a/docs/qa/img34/v034_r200c2_total-txs.png b/docs/references/qa/img34/v034_r200c2_total-txs.png similarity index 100% rename from docs/qa/img34/v034_r200c2_total-txs.png rename to docs/references/qa/img34/v034_r200c2_total-txs.png diff --git a/docs/qa/img34/v034_report_tabbed.txt b/docs/references/qa/img34/v034_report_tabbed.txt similarity index 100% rename from docs/qa/img34/v034_report_tabbed.txt rename to docs/references/qa/img34/v034_report_tabbed.txt diff --git a/docs/qa/img34/v034_rotating_heights.png b/docs/references/qa/img34/v034_rotating_heights.png similarity index 100% rename from docs/qa/img34/v034_rotating_heights.png rename to docs/references/qa/img34/v034_rotating_heights.png diff --git a/docs/qa/img34/v034_rotating_heights_ephe.png b/docs/references/qa/img34/v034_rotating_heights_ephe.png similarity index 100% rename from docs/qa/img34/v034_rotating_heights_ephe.png rename to docs/references/qa/img34/v034_rotating_heights_ephe.png diff --git a/docs/qa/img34/v034_rotating_latencies.png b/docs/references/qa/img34/v034_rotating_latencies.png similarity index 100% rename from docs/qa/img34/v034_rotating_latencies.png rename to docs/references/qa/img34/v034_rotating_latencies.png diff --git a/docs/qa/img34/v034_rotating_latencies_uniq.png b/docs/references/qa/img34/v034_rotating_latencies_uniq.png similarity index 100% rename from docs/qa/img34/v034_rotating_latencies_uniq.png rename to docs/references/qa/img34/v034_rotating_latencies_uniq.png diff --git a/docs/qa/img34/v034_rotating_load1.png b/docs/references/qa/img34/v034_rotating_load1.png similarity index 100% rename from docs/qa/img34/v034_rotating_load1.png rename to docs/references/qa/img34/v034_rotating_load1.png diff --git a/docs/qa/img34/v034_rotating_peers.png b/docs/references/qa/img34/v034_rotating_peers.png similarity index 100% rename from docs/qa/img34/v034_rotating_peers.png rename to docs/references/qa/img34/v034_rotating_peers.png diff --git a/docs/qa/img34/v034_rotating_rss_avg.png b/docs/references/qa/img34/v034_rotating_rss_avg.png similarity index 100% rename from docs/qa/img34/v034_rotating_rss_avg.png rename to docs/references/qa/img34/v034_rotating_rss_avg.png diff --git a/docs/qa/img34/v034_rotating_total-txs.png b/docs/references/qa/img34/v034_rotating_total-txs.png similarity index 100% rename from docs/qa/img34/v034_rotating_total-txs.png rename to docs/references/qa/img34/v034_rotating_total-txs.png diff --git a/docs/qa/img37/200nodes_cmt037/all_experiments.png b/docs/references/qa/img37/200nodes_cmt037/all_experiments.png similarity index 100% rename from docs/qa/img37/200nodes_cmt037/all_experiments.png rename to docs/references/qa/img37/200nodes_cmt037/all_experiments.png diff --git a/docs/qa/img37/200nodes_cmt037/avg_mempool_size.png b/docs/references/qa/img37/200nodes_cmt037/avg_mempool_size.png similarity index 100% rename from docs/qa/img37/200nodes_cmt037/avg_mempool_size.png rename to docs/references/qa/img37/200nodes_cmt037/avg_mempool_size.png diff --git a/docs/qa/img37/200nodes_cmt037/block_rate.png b/docs/references/qa/img37/200nodes_cmt037/block_rate.png similarity index 100% rename from docs/qa/img37/200nodes_cmt037/block_rate.png rename to docs/references/qa/img37/200nodes_cmt037/block_rate.png diff --git a/docs/qa/img37/200nodes_cmt037/cpu.png b/docs/references/qa/img37/200nodes_cmt037/cpu.png similarity index 100% rename from docs/qa/img37/200nodes_cmt037/cpu.png rename to docs/references/qa/img37/200nodes_cmt037/cpu.png diff --git a/docs/qa/img37/200nodes_cmt037/e_75cb89a8-f876-4698-82f3-8aaab0b361af.png b/docs/references/qa/img37/200nodes_cmt037/e_75cb89a8-f876-4698-82f3-8aaab0b361af.png similarity index 100% rename from docs/qa/img37/200nodes_cmt037/e_75cb89a8-f876-4698-82f3-8aaab0b361af.png rename to docs/references/qa/img37/200nodes_cmt037/e_75cb89a8-f876-4698-82f3-8aaab0b361af.png diff --git a/docs/qa/img37/200nodes_cmt037/memory.png b/docs/references/qa/img37/200nodes_cmt037/memory.png similarity index 100% rename from docs/qa/img37/200nodes_cmt037/memory.png rename to docs/references/qa/img37/200nodes_cmt037/memory.png diff --git a/docs/qa/img37/200nodes_cmt037/mempool_size.png b/docs/references/qa/img37/200nodes_cmt037/mempool_size.png similarity index 100% rename from docs/qa/img37/200nodes_cmt037/mempool_size.png rename to docs/references/qa/img37/200nodes_cmt037/mempool_size.png diff --git a/docs/qa/img37/200nodes_cmt037/peers.png b/docs/references/qa/img37/200nodes_cmt037/peers.png similarity index 100% rename from docs/qa/img37/200nodes_cmt037/peers.png rename to docs/references/qa/img37/200nodes_cmt037/peers.png diff --git a/docs/qa/img37/200nodes_cmt037/rounds.png b/docs/references/qa/img37/200nodes_cmt037/rounds.png similarity index 100% rename from docs/qa/img37/200nodes_cmt037/rounds.png rename to docs/references/qa/img37/200nodes_cmt037/rounds.png diff --git a/docs/qa/img37/200nodes_cmt037/total_txs_rate.png b/docs/references/qa/img37/200nodes_cmt037/total_txs_rate.png similarity index 100% rename from docs/qa/img37/200nodes_cmt037/total_txs_rate.png rename to docs/references/qa/img37/200nodes_cmt037/total_txs_rate.png diff --git a/docs/qa/img37/200nodes_tm037/avg_mempool_size.png b/docs/references/qa/img37/200nodes_tm037/avg_mempool_size.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/avg_mempool_size.png rename to docs/references/qa/img37/200nodes_tm037/avg_mempool_size.png diff --git a/docs/qa/img37/200nodes_tm037/block_rate_regular.png b/docs/references/qa/img37/200nodes_tm037/block_rate_regular.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/block_rate_regular.png rename to docs/references/qa/img37/200nodes_tm037/block_rate_regular.png diff --git a/docs/qa/img37/200nodes_tm037/cpu.png b/docs/references/qa/img37/200nodes_tm037/cpu.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/cpu.png rename to docs/references/qa/img37/200nodes_tm037/cpu.png diff --git a/docs/qa/img37/200nodes_tm037/memory.png b/docs/references/qa/img37/200nodes_tm037/memory.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/memory.png rename to docs/references/qa/img37/200nodes_tm037/memory.png diff --git a/docs/qa/img37/200nodes_tm037/mempool_size.png b/docs/references/qa/img37/200nodes_tm037/mempool_size.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/mempool_size.png rename to docs/references/qa/img37/200nodes_tm037/mempool_size.png diff --git a/docs/qa/img37/200nodes_tm037/peers.png b/docs/references/qa/img37/200nodes_tm037/peers.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/peers.png rename to docs/references/qa/img37/200nodes_tm037/peers.png diff --git a/docs/qa/img37/200nodes_tm037/rounds.png b/docs/references/qa/img37/200nodes_tm037/rounds.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/rounds.png rename to docs/references/qa/img37/200nodes_tm037/rounds.png diff --git a/docs/qa/img37/200nodes_tm037/total_txs_rate_regular.png b/docs/references/qa/img37/200nodes_tm037/total_txs_rate_regular.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/total_txs_rate_regular.png rename to docs/references/qa/img37/200nodes_tm037/total_txs_rate_regular.png diff --git a/docs/qa/img37/200nodes_tm037/v037_200node_latencies.png b/docs/references/qa/img37/200nodes_tm037/v037_200node_latencies.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_200node_latencies.png rename to docs/references/qa/img37/200nodes_tm037/v037_200node_latencies.png diff --git a/docs/qa/img37/200nodes_tm037/v037_latency_throughput.png b/docs/references/qa/img37/200nodes_tm037/v037_latency_throughput.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_latency_throughput.png rename to docs/references/qa/img37/200nodes_tm037/v037_latency_throughput.png diff --git a/docs/qa/img37/200nodes_tm037/v037_r200c2_heights.png b/docs/references/qa/img37/200nodes_tm037/v037_r200c2_heights.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_r200c2_heights.png rename to docs/references/qa/img37/200nodes_tm037/v037_r200c2_heights.png diff --git a/docs/qa/img37/200nodes_tm037/v037_r200c2_load1.png b/docs/references/qa/img37/200nodes_tm037/v037_r200c2_load1.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_r200c2_load1.png rename to docs/references/qa/img37/200nodes_tm037/v037_r200c2_load1.png diff --git a/docs/qa/img37/200nodes_tm037/v037_r200c2_mempool_size.png b/docs/references/qa/img37/200nodes_tm037/v037_r200c2_mempool_size.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_r200c2_mempool_size.png rename to docs/references/qa/img37/200nodes_tm037/v037_r200c2_mempool_size.png diff --git a/docs/qa/img37/200nodes_tm037/v037_r200c2_mempool_size_avg.png b/docs/references/qa/img37/200nodes_tm037/v037_r200c2_mempool_size_avg.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_r200c2_mempool_size_avg.png rename to docs/references/qa/img37/200nodes_tm037/v037_r200c2_mempool_size_avg.png diff --git a/docs/qa/img37/200nodes_tm037/v037_r200c2_peers.png b/docs/references/qa/img37/200nodes_tm037/v037_r200c2_peers.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_r200c2_peers.png rename to docs/references/qa/img37/200nodes_tm037/v037_r200c2_peers.png diff --git a/docs/qa/img37/200nodes_tm037/v037_r200c2_rounds.png b/docs/references/qa/img37/200nodes_tm037/v037_r200c2_rounds.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_r200c2_rounds.png rename to docs/references/qa/img37/200nodes_tm037/v037_r200c2_rounds.png diff --git a/docs/qa/img37/200nodes_tm037/v037_r200c2_rss.png b/docs/references/qa/img37/200nodes_tm037/v037_r200c2_rss.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_r200c2_rss.png rename to docs/references/qa/img37/200nodes_tm037/v037_r200c2_rss.png diff --git a/docs/qa/img37/200nodes_tm037/v037_r200c2_rss_avg.png b/docs/references/qa/img37/200nodes_tm037/v037_r200c2_rss_avg.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_r200c2_rss_avg.png rename to docs/references/qa/img37/200nodes_tm037/v037_r200c2_rss_avg.png diff --git a/docs/qa/img37/200nodes_tm037/v037_r200c2_total-txs.png b/docs/references/qa/img37/200nodes_tm037/v037_r200c2_total-txs.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_r200c2_total-txs.png rename to docs/references/qa/img37/200nodes_tm037/v037_r200c2_total-txs.png diff --git a/docs/qa/img37/200nodes_tm037/v037_report_tabbed.txt b/docs/references/qa/img37/200nodes_tm037/v037_report_tabbed.txt similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_report_tabbed.txt rename to docs/references/qa/img37/200nodes_tm037/v037_report_tabbed.txt diff --git a/docs/qa/img37/200nodes_tm037/v037_rotating_heights.png b/docs/references/qa/img37/200nodes_tm037/v037_rotating_heights.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_rotating_heights.png rename to docs/references/qa/img37/200nodes_tm037/v037_rotating_heights.png diff --git a/docs/qa/img37/200nodes_tm037/v037_rotating_heights_ephe.png b/docs/references/qa/img37/200nodes_tm037/v037_rotating_heights_ephe.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_rotating_heights_ephe.png rename to docs/references/qa/img37/200nodes_tm037/v037_rotating_heights_ephe.png diff --git a/docs/qa/img37/200nodes_tm037/v037_rotating_latencies.png b/docs/references/qa/img37/200nodes_tm037/v037_rotating_latencies.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_rotating_latencies.png rename to docs/references/qa/img37/200nodes_tm037/v037_rotating_latencies.png diff --git a/docs/qa/img37/200nodes_tm037/v037_rotating_load1.png b/docs/references/qa/img37/200nodes_tm037/v037_rotating_load1.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_rotating_load1.png rename to docs/references/qa/img37/200nodes_tm037/v037_rotating_load1.png diff --git a/docs/qa/img37/200nodes_tm037/v037_rotating_peers.png b/docs/references/qa/img37/200nodes_tm037/v037_rotating_peers.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_rotating_peers.png rename to docs/references/qa/img37/200nodes_tm037/v037_rotating_peers.png diff --git a/docs/qa/img37/200nodes_tm037/v037_rotating_rss_avg.png b/docs/references/qa/img37/200nodes_tm037/v037_rotating_rss_avg.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_rotating_rss_avg.png rename to docs/references/qa/img37/200nodes_tm037/v037_rotating_rss_avg.png diff --git a/docs/qa/img37/200nodes_tm037/v037_rotating_total-txs.png b/docs/references/qa/img37/200nodes_tm037/v037_rotating_total-txs.png similarity index 100% rename from docs/qa/img37/200nodes_tm037/v037_rotating_total-txs.png rename to docs/references/qa/img37/200nodes_tm037/v037_rotating_total-txs.png diff --git a/docs/qa/img37/rotating/rotating_avg_memory.png b/docs/references/qa/img37/rotating/rotating_avg_memory.png similarity index 100% rename from docs/qa/img37/rotating/rotating_avg_memory.png rename to docs/references/qa/img37/rotating/rotating_avg_memory.png diff --git a/docs/qa/img37/rotating/rotating_block_rate.png b/docs/references/qa/img37/rotating/rotating_block_rate.png similarity index 100% rename from docs/qa/img37/rotating/rotating_block_rate.png rename to docs/references/qa/img37/rotating/rotating_block_rate.png diff --git a/docs/qa/img37/rotating/rotating_cpu.png b/docs/references/qa/img37/rotating/rotating_cpu.png similarity index 100% rename from docs/qa/img37/rotating/rotating_cpu.png rename to docs/references/qa/img37/rotating/rotating_cpu.png diff --git a/docs/qa/img37/rotating/rotating_eph_heights.png b/docs/references/qa/img37/rotating/rotating_eph_heights.png similarity index 100% rename from docs/qa/img37/rotating/rotating_eph_heights.png rename to docs/references/qa/img37/rotating/rotating_eph_heights.png diff --git a/docs/qa/img37/rotating/rotating_peers.png b/docs/references/qa/img37/rotating/rotating_peers.png similarity index 100% rename from docs/qa/img37/rotating/rotating_peers.png rename to docs/references/qa/img37/rotating/rotating_peers.png diff --git a/docs/qa/img37/rotating/rotating_txs_rate.png b/docs/references/qa/img37/rotating/rotating_txs_rate.png similarity index 100% rename from docs/qa/img37/rotating/rotating_txs_rate.png rename to docs/references/qa/img37/rotating/rotating_txs_rate.png diff --git a/docs/qa/img38/200nodes/avg_mempool_size.png b/docs/references/qa/img38/200nodes/avg_mempool_size.png similarity index 100% rename from docs/qa/img38/200nodes/avg_mempool_size.png rename to docs/references/qa/img38/200nodes/avg_mempool_size.png diff --git a/docs/qa/img38/200nodes/block_rate.png b/docs/references/qa/img38/200nodes/block_rate.png similarity index 100% rename from docs/qa/img38/200nodes/block_rate.png rename to docs/references/qa/img38/200nodes/block_rate.png diff --git a/docs/qa/img38/200nodes/c1r400.png b/docs/references/qa/img38/200nodes/c1r400.png similarity index 100% rename from docs/qa/img38/200nodes/c1r400.png rename to docs/references/qa/img38/200nodes/c1r400.png diff --git a/docs/qa/img38/200nodes/cpu.png b/docs/references/qa/img38/200nodes/cpu.png similarity index 100% rename from docs/qa/img38/200nodes/cpu.png rename to docs/references/qa/img38/200nodes/cpu.png diff --git a/docs/qa/img38/200nodes/e_de676ecf-038e-443f-a26a-27915f29e312.png b/docs/references/qa/img38/200nodes/e_de676ecf-038e-443f-a26a-27915f29e312.png similarity index 100% rename from docs/qa/img38/200nodes/e_de676ecf-038e-443f-a26a-27915f29e312.png rename to docs/references/qa/img38/200nodes/e_de676ecf-038e-443f-a26a-27915f29e312.png diff --git a/docs/qa/img38/200nodes/memory.png b/docs/references/qa/img38/200nodes/memory.png similarity index 100% rename from docs/qa/img38/200nodes/memory.png rename to docs/references/qa/img38/200nodes/memory.png diff --git a/docs/qa/img38/200nodes/mempool_size.png b/docs/references/qa/img38/200nodes/mempool_size.png similarity index 100% rename from docs/qa/img38/200nodes/mempool_size.png rename to docs/references/qa/img38/200nodes/mempool_size.png diff --git a/docs/qa/img38/200nodes/peers.png b/docs/references/qa/img38/200nodes/peers.png similarity index 100% rename from docs/qa/img38/200nodes/peers.png rename to docs/references/qa/img38/200nodes/peers.png diff --git a/docs/qa/img38/200nodes/rounds.png b/docs/references/qa/img38/200nodes/rounds.png similarity index 100% rename from docs/qa/img38/200nodes/rounds.png rename to docs/references/qa/img38/200nodes/rounds.png diff --git a/docs/qa/img38/200nodes/total_txs_rate.png b/docs/references/qa/img38/200nodes/total_txs_rate.png similarity index 100% rename from docs/qa/img38/200nodes/total_txs_rate.png rename to docs/references/qa/img38/200nodes/total_txs_rate.png diff --git a/docs/qa/img38/200nodes/v038_report_tabbed.txt b/docs/references/qa/img38/200nodes/v038_report_tabbed.txt similarity index 100% rename from docs/qa/img38/200nodes/v038_report_tabbed.txt rename to docs/references/qa/img38/200nodes/v038_report_tabbed.txt diff --git a/docs/qa/img38/rotating/rotating_avg_memory.png b/docs/references/qa/img38/rotating/rotating_avg_memory.png similarity index 100% rename from docs/qa/img38/rotating/rotating_avg_memory.png rename to docs/references/qa/img38/rotating/rotating_avg_memory.png diff --git a/docs/qa/img38/rotating/rotating_block_rate.png b/docs/references/qa/img38/rotating/rotating_block_rate.png similarity index 100% rename from docs/qa/img38/rotating/rotating_block_rate.png rename to docs/references/qa/img38/rotating/rotating_block_rate.png diff --git a/docs/qa/img38/rotating/rotating_cpu.png b/docs/references/qa/img38/rotating/rotating_cpu.png similarity index 100% rename from docs/qa/img38/rotating/rotating_cpu.png rename to docs/references/qa/img38/rotating/rotating_cpu.png diff --git a/docs/qa/img38/rotating/rotating_eph_heights.png b/docs/references/qa/img38/rotating/rotating_eph_heights.png similarity index 100% rename from docs/qa/img38/rotating/rotating_eph_heights.png rename to docs/references/qa/img38/rotating/rotating_eph_heights.png diff --git a/docs/qa/img38/rotating/rotating_latencies.png b/docs/references/qa/img38/rotating/rotating_latencies.png similarity index 100% rename from docs/qa/img38/rotating/rotating_latencies.png rename to docs/references/qa/img38/rotating/rotating_latencies.png diff --git a/docs/qa/img38/rotating/rotating_peers.png b/docs/references/qa/img38/rotating/rotating_peers.png similarity index 100% rename from docs/qa/img38/rotating/rotating_peers.png rename to docs/references/qa/img38/rotating/rotating_peers.png diff --git a/docs/qa/img38/rotating/rotating_txs_rate.png b/docs/references/qa/img38/rotating/rotating_txs_rate.png similarity index 100% rename from docs/qa/img38/rotating/rotating_txs_rate.png rename to docs/references/qa/img38/rotating/rotating_txs_rate.png diff --git a/docs/qa/img38/voteExtensions/02k_1_block_rate.png b/docs/references/qa/img38/voteExtensions/02k_1_block_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/02k_1_block_rate.png rename to docs/references/qa/img38/voteExtensions/02k_1_block_rate.png diff --git a/docs/qa/img38/voteExtensions/02k_1_total_txs_rate.png b/docs/references/qa/img38/voteExtensions/02k_1_total_txs_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/02k_1_total_txs_rate.png rename to docs/references/qa/img38/voteExtensions/02k_1_total_txs_rate.png diff --git a/docs/qa/img38/voteExtensions/02k_avg_cpu.png b/docs/references/qa/img38/voteExtensions/02k_avg_cpu.png similarity index 100% rename from docs/qa/img38/voteExtensions/02k_avg_cpu.png rename to docs/references/qa/img38/voteExtensions/02k_avg_cpu.png diff --git a/docs/qa/img38/voteExtensions/02k_avg_memory.png b/docs/references/qa/img38/voteExtensions/02k_avg_memory.png similarity index 100% rename from docs/qa/img38/voteExtensions/02k_avg_memory.png rename to docs/references/qa/img38/voteExtensions/02k_avg_memory.png diff --git a/docs/qa/img38/voteExtensions/02k_avg_mempool_size.png b/docs/references/qa/img38/voteExtensions/02k_avg_mempool_size.png similarity index 100% rename from docs/qa/img38/voteExtensions/02k_avg_mempool_size.png rename to docs/references/qa/img38/voteExtensions/02k_avg_mempool_size.png diff --git a/docs/qa/img38/voteExtensions/02k_block_rate.png b/docs/references/qa/img38/voteExtensions/02k_block_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/02k_block_rate.png rename to docs/references/qa/img38/voteExtensions/02k_block_rate.png diff --git a/docs/qa/img38/voteExtensions/02k_rounds.png b/docs/references/qa/img38/voteExtensions/02k_rounds.png similarity index 100% rename from docs/qa/img38/voteExtensions/02k_rounds.png rename to docs/references/qa/img38/voteExtensions/02k_rounds.png diff --git a/docs/qa/img38/voteExtensions/02k_total_txs_rate.png b/docs/references/qa/img38/voteExtensions/02k_total_txs_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/02k_total_txs_rate.png rename to docs/references/qa/img38/voteExtensions/02k_total_txs_rate.png diff --git a/docs/qa/img38/voteExtensions/04k_1_block_rate.png b/docs/references/qa/img38/voteExtensions/04k_1_block_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/04k_1_block_rate.png rename to docs/references/qa/img38/voteExtensions/04k_1_block_rate.png diff --git a/docs/qa/img38/voteExtensions/04k_1_total_txs_rate.png b/docs/references/qa/img38/voteExtensions/04k_1_total_txs_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/04k_1_total_txs_rate.png rename to docs/references/qa/img38/voteExtensions/04k_1_total_txs_rate.png diff --git a/docs/qa/img38/voteExtensions/04k_avg_cpu.png b/docs/references/qa/img38/voteExtensions/04k_avg_cpu.png similarity index 100% rename from docs/qa/img38/voteExtensions/04k_avg_cpu.png rename to docs/references/qa/img38/voteExtensions/04k_avg_cpu.png diff --git a/docs/qa/img38/voteExtensions/04k_avg_memory.png b/docs/references/qa/img38/voteExtensions/04k_avg_memory.png similarity index 100% rename from docs/qa/img38/voteExtensions/04k_avg_memory.png rename to docs/references/qa/img38/voteExtensions/04k_avg_memory.png diff --git a/docs/qa/img38/voteExtensions/04k_avg_mempool_size.png b/docs/references/qa/img38/voteExtensions/04k_avg_mempool_size.png similarity index 100% rename from docs/qa/img38/voteExtensions/04k_avg_mempool_size.png rename to docs/references/qa/img38/voteExtensions/04k_avg_mempool_size.png diff --git a/docs/qa/img38/voteExtensions/04k_block_rate.png b/docs/references/qa/img38/voteExtensions/04k_block_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/04k_block_rate.png rename to docs/references/qa/img38/voteExtensions/04k_block_rate.png diff --git a/docs/qa/img38/voteExtensions/04k_rounds.png b/docs/references/qa/img38/voteExtensions/04k_rounds.png similarity index 100% rename from docs/qa/img38/voteExtensions/04k_rounds.png rename to docs/references/qa/img38/voteExtensions/04k_rounds.png diff --git a/docs/qa/img38/voteExtensions/04k_total_txs_rate.png b/docs/references/qa/img38/voteExtensions/04k_total_txs_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/04k_total_txs_rate.png rename to docs/references/qa/img38/voteExtensions/04k_total_txs_rate.png diff --git a/docs/qa/img38/voteExtensions/08k_1_avg_mempool_size.png b/docs/references/qa/img38/voteExtensions/08k_1_avg_mempool_size.png similarity index 100% rename from docs/qa/img38/voteExtensions/08k_1_avg_mempool_size.png rename to docs/references/qa/img38/voteExtensions/08k_1_avg_mempool_size.png diff --git a/docs/qa/img38/voteExtensions/08k_1_block_rate.png b/docs/references/qa/img38/voteExtensions/08k_1_block_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/08k_1_block_rate.png rename to docs/references/qa/img38/voteExtensions/08k_1_block_rate.png diff --git a/docs/qa/img38/voteExtensions/08k_1_rounds.png b/docs/references/qa/img38/voteExtensions/08k_1_rounds.png similarity index 100% rename from docs/qa/img38/voteExtensions/08k_1_rounds.png rename to docs/references/qa/img38/voteExtensions/08k_1_rounds.png diff --git a/docs/qa/img38/voteExtensions/08k_1_total_txs_rate.png b/docs/references/qa/img38/voteExtensions/08k_1_total_txs_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/08k_1_total_txs_rate.png rename to docs/references/qa/img38/voteExtensions/08k_1_total_txs_rate.png diff --git a/docs/qa/img38/voteExtensions/08k_avg_cpu.png b/docs/references/qa/img38/voteExtensions/08k_avg_cpu.png similarity index 100% rename from docs/qa/img38/voteExtensions/08k_avg_cpu.png rename to docs/references/qa/img38/voteExtensions/08k_avg_cpu.png diff --git a/docs/qa/img38/voteExtensions/08k_avg_memory.png b/docs/references/qa/img38/voteExtensions/08k_avg_memory.png similarity index 100% rename from docs/qa/img38/voteExtensions/08k_avg_memory.png rename to docs/references/qa/img38/voteExtensions/08k_avg_memory.png diff --git a/docs/qa/img38/voteExtensions/08k_avg_mempool_size.png b/docs/references/qa/img38/voteExtensions/08k_avg_mempool_size.png similarity index 100% rename from docs/qa/img38/voteExtensions/08k_avg_mempool_size.png rename to docs/references/qa/img38/voteExtensions/08k_avg_mempool_size.png diff --git a/docs/qa/img38/voteExtensions/08k_rounds.png b/docs/references/qa/img38/voteExtensions/08k_rounds.png similarity index 100% rename from docs/qa/img38/voteExtensions/08k_rounds.png rename to docs/references/qa/img38/voteExtensions/08k_rounds.png diff --git a/docs/qa/img38/voteExtensions/08k_total_txs_rate.png b/docs/references/qa/img38/voteExtensions/08k_total_txs_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/08k_total_txs_rate.png rename to docs/references/qa/img38/voteExtensions/08k_total_txs_rate.png diff --git a/docs/qa/img38/voteExtensions/16k_1_avg_mempool_size.png b/docs/references/qa/img38/voteExtensions/16k_1_avg_mempool_size.png similarity index 100% rename from docs/qa/img38/voteExtensions/16k_1_avg_mempool_size.png rename to docs/references/qa/img38/voteExtensions/16k_1_avg_mempool_size.png diff --git a/docs/qa/img38/voteExtensions/16k_1_block_rate.png b/docs/references/qa/img38/voteExtensions/16k_1_block_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/16k_1_block_rate.png rename to docs/references/qa/img38/voteExtensions/16k_1_block_rate.png diff --git a/docs/qa/img38/voteExtensions/16k_1_rounds.png b/docs/references/qa/img38/voteExtensions/16k_1_rounds.png similarity index 100% rename from docs/qa/img38/voteExtensions/16k_1_rounds.png rename to docs/references/qa/img38/voteExtensions/16k_1_rounds.png diff --git a/docs/qa/img38/voteExtensions/16k_1_total_txs_rate.png b/docs/references/qa/img38/voteExtensions/16k_1_total_txs_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/16k_1_total_txs_rate.png rename to docs/references/qa/img38/voteExtensions/16k_1_total_txs_rate.png diff --git a/docs/qa/img38/voteExtensions/16k_avg_cpu.png b/docs/references/qa/img38/voteExtensions/16k_avg_cpu.png similarity index 100% rename from docs/qa/img38/voteExtensions/16k_avg_cpu.png rename to docs/references/qa/img38/voteExtensions/16k_avg_cpu.png diff --git a/docs/qa/img38/voteExtensions/16k_avg_memory.png b/docs/references/qa/img38/voteExtensions/16k_avg_memory.png similarity index 100% rename from docs/qa/img38/voteExtensions/16k_avg_memory.png rename to docs/references/qa/img38/voteExtensions/16k_avg_memory.png diff --git a/docs/qa/img38/voteExtensions/16k_avg_mempool_size.png b/docs/references/qa/img38/voteExtensions/16k_avg_mempool_size.png similarity index 100% rename from docs/qa/img38/voteExtensions/16k_avg_mempool_size.png rename to docs/references/qa/img38/voteExtensions/16k_avg_mempool_size.png diff --git a/docs/qa/img38/voteExtensions/16k_block_rate.png b/docs/references/qa/img38/voteExtensions/16k_block_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/16k_block_rate.png rename to docs/references/qa/img38/voteExtensions/16k_block_rate.png diff --git a/docs/qa/img38/voteExtensions/16k_rounds.png b/docs/references/qa/img38/voteExtensions/16k_rounds.png similarity index 100% rename from docs/qa/img38/voteExtensions/16k_rounds.png rename to docs/references/qa/img38/voteExtensions/16k_rounds.png diff --git a/docs/qa/img38/voteExtensions/16k_total_txs_rate.png b/docs/references/qa/img38/voteExtensions/16k_total_txs_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/16k_total_txs_rate.png rename to docs/references/qa/img38/voteExtensions/16k_total_txs_rate.png diff --git a/docs/qa/img38/voteExtensions/32k_1_avg_mempool_size.png b/docs/references/qa/img38/voteExtensions/32k_1_avg_mempool_size.png similarity index 100% rename from docs/qa/img38/voteExtensions/32k_1_avg_mempool_size.png rename to docs/references/qa/img38/voteExtensions/32k_1_avg_mempool_size.png diff --git a/docs/qa/img38/voteExtensions/32k_1_block_rate.png b/docs/references/qa/img38/voteExtensions/32k_1_block_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/32k_1_block_rate.png rename to docs/references/qa/img38/voteExtensions/32k_1_block_rate.png diff --git a/docs/qa/img38/voteExtensions/32k_1_rounds.png b/docs/references/qa/img38/voteExtensions/32k_1_rounds.png similarity index 100% rename from docs/qa/img38/voteExtensions/32k_1_rounds.png rename to docs/references/qa/img38/voteExtensions/32k_1_rounds.png diff --git a/docs/qa/img38/voteExtensions/32k_1_total_txs_rate.png b/docs/references/qa/img38/voteExtensions/32k_1_total_txs_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/32k_1_total_txs_rate.png rename to docs/references/qa/img38/voteExtensions/32k_1_total_txs_rate.png diff --git a/docs/qa/img38/voteExtensions/32k_avg_cpu.png b/docs/references/qa/img38/voteExtensions/32k_avg_cpu.png similarity index 100% rename from docs/qa/img38/voteExtensions/32k_avg_cpu.png rename to docs/references/qa/img38/voteExtensions/32k_avg_cpu.png diff --git a/docs/qa/img38/voteExtensions/32k_avg_memory.png b/docs/references/qa/img38/voteExtensions/32k_avg_memory.png similarity index 100% rename from docs/qa/img38/voteExtensions/32k_avg_memory.png rename to docs/references/qa/img38/voteExtensions/32k_avg_memory.png diff --git a/docs/qa/img38/voteExtensions/32k_avg_mempool_size.png b/docs/references/qa/img38/voteExtensions/32k_avg_mempool_size.png similarity index 100% rename from docs/qa/img38/voteExtensions/32k_avg_mempool_size.png rename to docs/references/qa/img38/voteExtensions/32k_avg_mempool_size.png diff --git a/docs/qa/img38/voteExtensions/32k_block_rate.png b/docs/references/qa/img38/voteExtensions/32k_block_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/32k_block_rate.png rename to docs/references/qa/img38/voteExtensions/32k_block_rate.png diff --git a/docs/qa/img38/voteExtensions/32k_rounds.png b/docs/references/qa/img38/voteExtensions/32k_rounds.png similarity index 100% rename from docs/qa/img38/voteExtensions/32k_rounds.png rename to docs/references/qa/img38/voteExtensions/32k_rounds.png diff --git a/docs/qa/img38/voteExtensions/32k_total_txs_rate.png b/docs/references/qa/img38/voteExtensions/32k_total_txs_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/32k_total_txs_rate.png rename to docs/references/qa/img38/voteExtensions/32k_total_txs_rate.png diff --git a/docs/qa/img38/voteExtensions/8k_block_rate.png b/docs/references/qa/img38/voteExtensions/8k_block_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/8k_block_rate.png rename to docs/references/qa/img38/voteExtensions/8k_block_rate.png diff --git a/docs/qa/img38/voteExtensions/all_c1r400_16k.png b/docs/references/qa/img38/voteExtensions/all_c1r400_16k.png similarity index 100% rename from docs/qa/img38/voteExtensions/all_c1r400_16k.png rename to docs/references/qa/img38/voteExtensions/all_c1r400_16k.png diff --git a/docs/qa/img38/voteExtensions/all_c1r400_2k.png b/docs/references/qa/img38/voteExtensions/all_c1r400_2k.png similarity index 100% rename from docs/qa/img38/voteExtensions/all_c1r400_2k.png rename to docs/references/qa/img38/voteExtensions/all_c1r400_2k.png diff --git a/docs/qa/img38/voteExtensions/all_c1r400_32k.png b/docs/references/qa/img38/voteExtensions/all_c1r400_32k.png similarity index 100% rename from docs/qa/img38/voteExtensions/all_c1r400_32k.png rename to docs/references/qa/img38/voteExtensions/all_c1r400_32k.png diff --git a/docs/qa/img38/voteExtensions/all_c1r400_4k.png b/docs/references/qa/img38/voteExtensions/all_c1r400_4k.png similarity index 100% rename from docs/qa/img38/voteExtensions/all_c1r400_4k.png rename to docs/references/qa/img38/voteExtensions/all_c1r400_4k.png diff --git a/docs/qa/img38/voteExtensions/all_c1r400_64k.png b/docs/references/qa/img38/voteExtensions/all_c1r400_64k.png similarity index 100% rename from docs/qa/img38/voteExtensions/all_c1r400_64k.png rename to docs/references/qa/img38/voteExtensions/all_c1r400_64k.png diff --git a/docs/qa/img38/voteExtensions/all_c1r400_8k.png b/docs/references/qa/img38/voteExtensions/all_c1r400_8k.png similarity index 100% rename from docs/qa/img38/voteExtensions/all_c1r400_8k.png rename to docs/references/qa/img38/voteExtensions/all_c1r400_8k.png diff --git a/docs/qa/img38/voteExtensions/all_c1r400_baseline.png b/docs/references/qa/img38/voteExtensions/all_c1r400_baseline.png similarity index 100% rename from docs/qa/img38/voteExtensions/all_c1r400_baseline.png rename to docs/references/qa/img38/voteExtensions/all_c1r400_baseline.png diff --git a/docs/qa/img38/voteExtensions/all_experiments_16k.png b/docs/references/qa/img38/voteExtensions/all_experiments_16k.png similarity index 100% rename from docs/qa/img38/voteExtensions/all_experiments_16k.png rename to docs/references/qa/img38/voteExtensions/all_experiments_16k.png diff --git a/docs/qa/img38/voteExtensions/all_experiments_2k.png b/docs/references/qa/img38/voteExtensions/all_experiments_2k.png similarity index 100% rename from docs/qa/img38/voteExtensions/all_experiments_2k.png rename to docs/references/qa/img38/voteExtensions/all_experiments_2k.png diff --git a/docs/qa/img38/voteExtensions/all_experiments_32k.png b/docs/references/qa/img38/voteExtensions/all_experiments_32k.png similarity index 100% rename from docs/qa/img38/voteExtensions/all_experiments_32k.png rename to docs/references/qa/img38/voteExtensions/all_experiments_32k.png diff --git a/docs/qa/img38/voteExtensions/all_experiments_4k.png b/docs/references/qa/img38/voteExtensions/all_experiments_4k.png similarity index 100% rename from docs/qa/img38/voteExtensions/all_experiments_4k.png rename to docs/references/qa/img38/voteExtensions/all_experiments_4k.png diff --git a/docs/qa/img38/voteExtensions/all_experiments_64k.png b/docs/references/qa/img38/voteExtensions/all_experiments_64k.png similarity index 100% rename from docs/qa/img38/voteExtensions/all_experiments_64k.png rename to docs/references/qa/img38/voteExtensions/all_experiments_64k.png diff --git a/docs/qa/img38/voteExtensions/all_experiments_8k.png b/docs/references/qa/img38/voteExtensions/all_experiments_8k.png similarity index 100% rename from docs/qa/img38/voteExtensions/all_experiments_8k.png rename to docs/references/qa/img38/voteExtensions/all_experiments_8k.png diff --git a/docs/qa/img38/voteExtensions/all_experiments_baseline.png b/docs/references/qa/img38/voteExtensions/all_experiments_baseline.png similarity index 100% rename from docs/qa/img38/voteExtensions/all_experiments_baseline.png rename to docs/references/qa/img38/voteExtensions/all_experiments_baseline.png diff --git a/docs/qa/img38/voteExtensions/baseline_1_avg_mempool_size.png b/docs/references/qa/img38/voteExtensions/baseline_1_avg_mempool_size.png similarity index 100% rename from docs/qa/img38/voteExtensions/baseline_1_avg_mempool_size.png rename to docs/references/qa/img38/voteExtensions/baseline_1_avg_mempool_size.png diff --git a/docs/qa/img38/voteExtensions/baseline_1_block_rate.png b/docs/references/qa/img38/voteExtensions/baseline_1_block_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/baseline_1_block_rate.png rename to docs/references/qa/img38/voteExtensions/baseline_1_block_rate.png diff --git a/docs/qa/img38/voteExtensions/baseline_1_rounds.png b/docs/references/qa/img38/voteExtensions/baseline_1_rounds.png similarity index 100% rename from docs/qa/img38/voteExtensions/baseline_1_rounds.png rename to docs/references/qa/img38/voteExtensions/baseline_1_rounds.png diff --git a/docs/qa/img38/voteExtensions/baseline_1_total_txs_rate.png b/docs/references/qa/img38/voteExtensions/baseline_1_total_txs_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/baseline_1_total_txs_rate.png rename to docs/references/qa/img38/voteExtensions/baseline_1_total_txs_rate.png diff --git a/docs/qa/img38/voteExtensions/baseline_avg_cpu.png b/docs/references/qa/img38/voteExtensions/baseline_avg_cpu.png similarity index 100% rename from docs/qa/img38/voteExtensions/baseline_avg_cpu.png rename to docs/references/qa/img38/voteExtensions/baseline_avg_cpu.png diff --git a/docs/qa/img38/voteExtensions/baseline_avg_memory.png b/docs/references/qa/img38/voteExtensions/baseline_avg_memory.png similarity index 100% rename from docs/qa/img38/voteExtensions/baseline_avg_memory.png rename to docs/references/qa/img38/voteExtensions/baseline_avg_memory.png diff --git a/docs/qa/img38/voteExtensions/baseline_avg_mempool_size.png b/docs/references/qa/img38/voteExtensions/baseline_avg_mempool_size.png similarity index 100% rename from docs/qa/img38/voteExtensions/baseline_avg_mempool_size.png rename to docs/references/qa/img38/voteExtensions/baseline_avg_mempool_size.png diff --git a/docs/qa/img38/voteExtensions/baseline_block_rate.png b/docs/references/qa/img38/voteExtensions/baseline_block_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/baseline_block_rate.png rename to docs/references/qa/img38/voteExtensions/baseline_block_rate.png diff --git a/docs/qa/img38/voteExtensions/baseline_rounds.png b/docs/references/qa/img38/voteExtensions/baseline_rounds.png similarity index 100% rename from docs/qa/img38/voteExtensions/baseline_rounds.png rename to docs/references/qa/img38/voteExtensions/baseline_rounds.png diff --git a/docs/qa/img38/voteExtensions/baseline_total_txs_rate.png b/docs/references/qa/img38/voteExtensions/baseline_total_txs_rate.png similarity index 100% rename from docs/qa/img38/voteExtensions/baseline_total_txs_rate.png rename to docs/references/qa/img38/voteExtensions/baseline_total_txs_rate.png diff --git a/docs/qa/method.md b/docs/references/qa/method.md similarity index 96% rename from docs/qa/method.md rename to docs/references/qa/method.md index 464356f50ca..07ca8d5c14f 100644 --- a/docs/qa/method.md +++ b/docs/references/qa/method.md @@ -67,7 +67,7 @@ This section explains how the tests were carried out for reproducibility purpose and check the graph for the `cometbft_consensus_height` metric. All nodes should be increasing their heights. - * You can find the Prometheus node's IP address in `ansible/hosts` under section `[prometheus]`. + * You can find the Prometheus node's IP address in `ansible/hosts` under section `[prometheus]`. * The following URL will display the metrics `cometbft_consensus_height` and `cometbft_mempool_size`: ``` @@ -79,7 +79,7 @@ This section explains how the tests were carried out for reproducibility purpose * Run `make loadrunners-init`. This will copy the loader scripts to the `testnet-load-runner` node and install the load tool. * Find the IP address of the `testnet-load-runner` node in - `ansible/hosts` under section `[loadrunners]`. + `ansible/hosts` under section `[loadrunners]`. * `ssh` into `testnet-load-runner`. * Edit the script `/root/200-node-loadscript.sh` in the load runner node to provide the IP address of a full node (for example, @@ -119,7 +119,7 @@ The CometBFT team should improve it at every iteration to increase the amount of 1. Unzip the blockstore into a directory 2. To identify saturation points - 1. Extract the latency report for all the experiments. + 1. Extract the latency report for all the experiments. * Run these commands from the directory containing the `blockstore.db` folder. * It is advisable to adjust the hash in the `go run` command to the latest possible. * ```bash @@ -141,9 +141,9 @@ The CometBFT team should improve it at every iteration to increase the amount of 4. Generate file `report_tabbed.txt` by showing the contents `report01.txt`, `report02.txt`, `report04.txt` side by side * This effectively creates a table where rows are a particular tx rate and columns are a particular number of websocket connections. * Combine the column files into a single table file: - * Replace tabs by spaces in all column files. For example, + * Replace tabs by spaces in all column files. For example, `sed -i.bak 's/\t/ /g' results/report1.txt`. - * Merge the new column files into one: + * Merge the new column files into one: `paste results/report1.txt results/report2.txt results/report4.txt | column -s $'\t' -t > report_tabbed.txt` 3. To generate a latency vs throughput plot, extract the data as a CSV @@ -156,8 +156,8 @@ The CometBFT team should improve it at every iteration to increase the amount of This script generates a series of plots per experiment and configuration that may help with visualizing Latency vs Throughput variation. -[`latency_throughput.py`]: ../../scripts/qa/reporting/README.md#Latency-vs-Throughput-Plotting -[`latency_plotter.py`]: ../../scripts/qa/reporting/README.md#Latency-vs-Throughput-Plotting-version-2 +[`latency_throughput.py`]: ../../../scripts/qa/reporting/README.md#Latency-vs-Throughput-Plotting +[`latency_plotter.py`]: ../../../scripts/qa/reporting/README.md#Latency-vs-Throughput-Plotting-version-2 #### Extracting Prometheus Metrics @@ -168,7 +168,7 @@ The CometBFT team should improve it at every iteration to increase the amount of 4. Identify the time window you want to plot in your graphs. 5. Execute the [`prometheus_plotter.py`] script for the time window. -[`prometheus_plotter.py`]: ../../scripts/qa/reporting/README.md#prometheus-metrics +[`prometheus_plotter.py`]: ../../../scripts/qa/reporting/README.md#prometheus-metrics ## Rotating Node Testnet @@ -242,9 +242,9 @@ This section explains how the tests were carried out for reproducibility purpose * `make restart` 2. Run the test * `make runload` - This will repeat the tests `ITERATIONS` times every time it is invoked. - 3. Collect your data - * `make retrieve-data` + This will repeat the tests `ITERATIONS` times every time it is invoked. + 3. Collect your data + * `make retrieve-data` Gathers all relevant data from the testnet into the orchestrating machine, inside folder `experiments`. Two subfolders are created, one blockstore DB for a CometBFT validator and one for the Prometheus DB data. * Verify that the data was collected without errors with `zip -T` on the `prometheus.zip` file and (one of) the `blockstore.db.zip` file(s). diff --git a/docs/rfc/README.md b/docs/references/rfc/README.md similarity index 68% rename from docs/rfc/README.md rename to docs/references/rfc/README.md index ef7caac4b22..a12c0ffe4e9 100644 --- a/docs/rfc/README.md +++ b/docs/references/rfc/README.md @@ -15,7 +15,7 @@ discussion that might otherwise only be recorded in an ad-hoc way (for example, via gists or Google docs) that are difficult to discover for someone after the fact. An RFC _may_ give rise to more specific architectural _decisions_ for CometBFT, but those decisions must be recorded separately in -[Architecture Decision Records (ADR)](../architecture/). +[Architecture Decision Records (ADR)](../references/architecture/). As a rule of thumb, if you can articulate a specific question that needs to be answered, write an ADR. If you need to explore the topic and get input from @@ -32,7 +32,7 @@ An RFC should provide: substance of the discussion (links to other documents are fine here). - The **discussion**, the primary content of the document. -The [rfc-template.md](./rfc-template.md) file includes placeholders for these +The [rfc-template.md](rfc-template.md) file includes placeholders for these sections. ## Table of Contents @@ -42,11 +42,11 @@ relating to Tendermint Core prior to forking, please see [this list](./tendermint-core/). -- [RFC-100: ABCI Vote Extension Propagation](./rfc-100-abci-vote-extension-propag.md) -- [RFC-101: Banning peers based on ResponseCheckTx](./rfc-101-p2p-bad-peers-checktx.md) -- [RFC-102: Improve forward compatibility of proto-generated Rust code](./rfc-102-rust-gen-builders.md) -- [RFC-103: Incoming transactions when node is catching up](./rfc-103-incoming-txs-when-catching-up.md) -- [RFC-104: Internal messaging using the actor model](./rfc-104-actor-model.md) -- [RFC-105: Allowing Non-Determinism in `ProcessProposal`](./rfc-105-non-det-process-proposal.md) -- [RFC-106: Separation of non-idempotent methods in data companion API](./rfc-106-separate-stateful-methods.md) -- [RFC-107: Internal signalling using event observers](./rfc-107-event-observer.md) +- [RFC-100: ABCI Vote Extension Propagation](rfc-100-abci-vote-extension-propag.md) +- [RFC-101: Banning peers based on ResponseCheckTx](rfc-101-p2p-bad-peers-checktx.md) +- [RFC-102: Improve forward compatibility of proto-generated Rust code](rfc-102-rust-gen-builders.md) +- [RFC-103: Incoming transactions when node is catching up](rfc-103-incoming-txs-when-catching-up.md) +- [RFC-104: Internal messaging using the actor model](rfc-104-actor-model.md) +- [RFC-105: Allowing Non-Determinism in `ProcessProposal`](rfc-105-non-det-process-proposal.md) +- [RFC-106: Separation of non-idempotent methods in data companion API](rfc-106-separate-stateful-methods.md) +- [RFC-107: Internal signalling using event observers](rfc-107-event-observer.md) diff --git a/docs/rfc/images/rfc-103-optimization-comparison.png b/docs/references/rfc/images/rfc-103-optimization-comparison.png similarity index 100% rename from docs/rfc/images/rfc-103-optimization-comparison.png rename to docs/references/rfc/images/rfc-103-optimization-comparison.png diff --git a/docs/rfc/rfc-100-abci-vote-extension-propag.md b/docs/references/rfc/rfc-100-abci-vote-extension-propag.md similarity index 100% rename from docs/rfc/rfc-100-abci-vote-extension-propag.md rename to docs/references/rfc/rfc-100-abci-vote-extension-propag.md diff --git a/docs/rfc/rfc-101-p2p-bad-peers-checktx.md b/docs/references/rfc/rfc-101-p2p-bad-peers-checktx.md similarity index 85% rename from docs/rfc/rfc-101-p2p-bad-peers-checktx.md rename to docs/references/rfc/rfc-101-p2p-bad-peers-checktx.md index 6cf32d7b0e1..5bd61797a31 100644 --- a/docs/rfc/rfc-101-p2p-bad-peers-checktx.md +++ b/docs/references/rfc/rfc-101-p2p-bad-peers-checktx.md @@ -10,23 +10,23 @@ ## Abstract In CometBFT, nodes receive transactions either from external clients via RPC, -or from their peers via p2p. Upon receiving a transaction, a node runs `CheckTx` on it. This is +or from their peers via p2p. Upon receiving a transaction, a node runs `CheckTx` on it. This is an application specific check whose return code with a zero value indicates the transaction has passed this check, and can be added into the mempool. Any non-zero code indicates the transaction is not valid. Thus, the main role of `CheckTx` is to, as early as possible, prevent invalid transactions -from entering the mempool. +from entering the mempool. `CheckTx` will never place a transaction failing the check into the mempool. But there are scenarios where a, once valid, transaction can become invalid. And there are valid, non-malicious, scenarios in which a transaction will not pass this check (including nodes getting different transactions at different times, meaning some -of them might be obsolete at the time of the check; state changes upon block execution etc.). +of them might be obsolete at the time of the check; state changes upon block execution etc.). However, CometBFT users observed that there are transactions that can never have been or will never be valid. They thus propose to introduce a special response code for `CheckTx` to indicate this behaviour, and ban the peers who gossip such transactions. Additionally, users expressed a need for banning peers who -repeatedly send transactions failing `CheckTx`. +repeatedly send transactions failing `CheckTx`. -The main goal of this document is to analyse the cases where peers could be banned when they send +The main goal of this document is to analyse the cases where peers could be banned when they send transactions failing `CheckTx`, and provide the exact conditions that a peer and transaction have to satisfy in order to mark the peer as bad. @@ -38,121 +38,121 @@ potential changes to the existing mempool logic and implementation. This work was triggered by issue [#7918](https://github.com/tendermint/tendermint/issues/7918) and a related discussion in [#2185](https://github.com/tendermint/tendermint/issues/2185). Additionally, -there was a [proposal](https://github.com/tendermint/tendermint/issues/6523) -to disconnect from peers after they send us transactions that constantly fail `CheckTx`. While -the actual implementation of an additional response code for `CheckTx` is straight forward there -are certain correctness aspects to consider. The questions to answer, along with identified risks will be outlined in -the discussion. +there was a [proposal](https://github.com/tendermint/tendermint/issues/6523) +to disconnect from peers after they send us transactions that constantly fail `CheckTx`. While +the actual implementation of an additional response code for `CheckTx` is straight forward there +are certain correctness aspects to consider. The questions to answer, along with identified risks will be outlined in +the discussion. ### Existing issues and concerns -Before diving into the details, we collected a set of issues opened by various users, arguing for -this behaviour and explaining their needs. +Before diving into the details, we collected a set of issues opened by various users, arguing for +this behaviour and explaining their needs. - Celestia: [blacklisting peers that repeatedly send bad tx](https://github.com/celestiaorg/celestia-core/issues/867) and investigating how [Tendermint treats large Txs](https://github.com/celestiaorg/celestia-core/issues/243) - BigChainDb: [Handling proposers who propose bad blocks](https://github.com/bigchaindb/BEPs/issues/84) - IBC relayers: Nodes allow transactions with a wrong `minGas` and gossip them, and other nodes keep rejecting them. Problem seen with relayers where some nodes would have the `minGas` [parameter](https://github.com/cosmos/gaia/blob/5db8fcc9a229730f5115bed82d0f85b6db7184b4/contrib/testnets/test_platform/templates/app.toml#L8-L11) misconfigured. -- Gaia reported and [issue](https://github.com/cosmos/gaia/issues/2073) where misconfigured non-validator nodes were spamming the validatos with +- Gaia reported and [issue](https://github.com/cosmos/gaia/issues/2073) where misconfigured non-validator nodes were spamming the validatos with transactions that were too big. The debugging was long and it was not easy to realize what was going on. **Acceptable duplicate transactions** -Banning peers was also mentioned within [IBC-go](https://github.com/cosmos/ibc-go/issues/853#issuecomment-1032211020). However,the crux of the issue is preventing transactions with duplicate payload. While this is indeed undesired behaviour, this is not considered behaviour that should lead to banning a peer or even disconnecting from him. Duplicate transactions are in this case prevented using an application-specific solution. +Banning peers was also mentioned within [IBC-go](https://github.com/cosmos/ibc-go/issues/853#issuecomment-1032211020). However,the crux of the issue is preventing transactions with duplicate payload. While this is indeed undesired behaviour, this is not considered behaviour that should lead to banning a peer or even disconnecting from him. Duplicate transactions are in this case prevented using an application-specific solution. ### Current state of mempool/p2p interaction -Transactions received from a peer are handled within the [`Receive`](https://github.com/cometbft/cometbft/blob/ff0f98892f24aac11e46aeff2b6d2c0ad816701a/mempool/v0/reactor.go#L158) routine. +Transactions received from a peer are handled within the [`Receive`](https://github.com/cometbft/cometbft/blob/ff0f98892f24aac11e46aeff2b6d2c0ad816701a/mempool/v0/reactor.go#L158) routine. Currently, the mempool triggers a disconnect from a peer in the case of the following errors: - [Unknown message type](https://github.com/cometbft/cometbft/blob/main/mempool/reactor.go#L119) -However, disconnecting from a peer is not the same as banning the peer. The p2p layer will close the connection but -the peer can reconnect without any penalty, and if the peer it is connecting to is configured to be its persistent peer, +However, disconnecting from a peer is not the same as banning the peer. The p2p layer will close the connection but +the peer can reconnect without any penalty, and if the peer it is connecting to is configured to be its persistent peer, a reconnect will be initiated -from the node. +from the node. ### Current support for peer banning The p2p layer implements banning peers by marking them -as bad and removing them from the list of peers to connect to for *at least* a predefined amount of time. This is done by calling the +as bad and removing them from the list of peers to connect to for *at least* a predefined amount of time. This is done by calling the [`MarkBad`](https://github.com/cometbft/cometbft/blob/main/spec/p2p/implementation/addressbook.md#bad-peers) routine implemented by the `Switch`. -If the node does not set the amount of time to be banned, a default value is used. -Note that the timing parameter sets the lower bound for when a peer will be unbanned. +If the node does not set the amount of time to be banned, a default value is used. +Note that the timing parameter sets the lower bound for when a peer will be unbanned. But the p2p layer will only try to connect to banned peers if the node is not sufficiently connected. Thus the node has no explicit control on when a reconnect attempt will be triggered. -The application can blacklist peers via ABCI if the -[`filterPeers`](../../spec/abci/abci%2B%2B_app_requirements.md#peer-filtering) -config flag is set, by providing a set of peers to ban to CometBFT. +The application can blacklist peers via ABCI if the +[`filterPeers`](../../../spec/abci/abci++_app_requirements.md#peer-filtering) +config flag is set, by providing a set of peers to ban to CometBFT. If the discussion in this RFC deems a different banning mechanism is needed, the actual implementation and design of this mechanism will be discussed in a separate RFC. This mechanism should be generic, designed within the p2p layer and simply provide an interface for reactors to indicate peers to ban and for how long. It should not involve any mempool -specific design considerations. +specific design considerations. ## Discussion If this feature is to be implemented we need to clearly define the following: 1. What does banning a peer mean: - 1. A peer can be simply disconnected from. + 1. A peer can be simply disconnected from. 2. Peer is disconnected from and banned. 3. Conditions for the peer to be banned. -2. If `CheckTx` signals a peer should be banned, retrieve the ID of peers to ban. -3. Are there possible attack scenarios or unexpected behaviours by allowing this. +2. If `CheckTx` signals a peer should be banned, retrieve the ID of peers to ban. +3. Are there possible attack scenarios or unexpected behaviours by allowing this. -Any further mentions of `banning` will be agnostic to the actual way banning is implemented by the p2p layer. +Any further mentions of `banning` will be agnostic to the actual way banning is implemented by the p2p layer. -### 1. What does banning a peer mean +### 1. What does banning a peer mean -CometBFT recognizes that peers can accept transactions into their mempool as valid but then when the state changes, they can become invalid. -There are also transactions that are received that could never have been valid (for example due to misconfiguration on one node). -We thus differentiate two scenarios - a) where `CheckTx` fails due to reasons already +CometBFT recognizes that peers can accept transactions into their mempool as valid but then when the state changes, they can become invalid. +There are also transactions that are received that could never have been valid (for example due to misconfiguration on one node). +We thus differentiate two scenarios - a) where `CheckTx` fails due to reasons already known and b) where `CheckTx` deems a transaction could never have been valid. -For the sake of simplicity , in the remainder of the text we will distinguish the failures due to a) as failures -signaled with `ResponseCheckTx.code = 1` and the failures described in b), failures with `ResponseCheckTx.code > 1`, even though +For the sake of simplicity , in the remainder of the text we will distinguish the failures due to a) as failures +signaled with `ResponseCheckTx.code = 1` and the failures described in b), failures with `ResponseCheckTx.code > 1`, even though the way we actually mark them in the end might differ. -For a), a peer sends transactions that **repeatedly** fail CheckTx with `ResponseCheckTx.code = 1`, and is banned or disconnected from to avoid this. -In this case we need to define what repeatedly means. +For a), a peer sends transactions that **repeatedly** fail CheckTx with `ResponseCheckTx.code = 1`, and is banned or disconnected from to avoid this. +In this case we need to define what repeatedly means. -For b) we need to understand what is the potential reason a transaction could never have been valid on one node, but passes `CheckTx` on another node. +For b) we need to understand what is the potential reason a transaction could never have been valid on one node, but passes `CheckTx` on another node. We need to understand all the possible scenarios in which this can happen: -1. What happens if a node is misconfigured and allows, for example, very large transactions into the mempool. -This node would then gossip these transactions and they would always fail on other nodes. +1. What happens if a node is misconfigured and allows, for example, very large transactions into the mempool. +This node would then gossip these transactions and they would always fail on other nodes. Is this a scenario where we want nodes to disconnect from this peer and ban it but do not consider it malicious? 2. Are all other reasons for this to happen sign of malicious behaviour where a node explicitly lies? How can `CheckTx` pass on a valid node, but fail on another valid node with a `ResponseCheckTx.code > 1`? -If such behaviour is only possible when a peer is malicious, should this peer be punished or banned forever? Note that +If such behaviour is only possible when a peer is malicious, should this peer be punished or banned forever? Note that we cannot know whether a node is a validator in order for it to be punished. Gossiping this behaviour to other peers pro-actively -also entails a different set of problems with it - how do we know we can trust peers who tell us to ban other peers. For these reasons, understanding the actual reason for these failures can be left for future work. +also entails a different set of problems with it - how do we know we can trust peers who tell us to ban other peers. For these reasons, understanding the actual reason for these failures can be left for future work. -For now, we will disconnect and ban the peer regardless of the exact reason a transaction -is considered to never be valid. +For now, we will disconnect and ban the peer regardless of the exact reason a transaction +is considered to never be valid. #### **Banning for frequent CheckTx failures** If a node sends transactions that fail `CheckTx` but could be valid at some point, a peer should not be banned the first time this happens. -Only if this happens frequently enough should this be considered as spam. To define this behaviour we keep track how many times (`numFailures`) a peer -sent us invalid transactions within a time interval (`lastFailure`). This time interval should be reset every `failureResetInterval`. +Only if this happens frequently enough should this be considered as spam. To define this behaviour we keep track how many times (`numFailures`) a peer +sent us invalid transactions within a time interval (`lastFailure`). This time interval should be reset every `failureResetInterval`. For each peer, we should have a separate `numFailures` and `lastFailure` variable. There is no need to have one per transaction. - Whenever a transaction fails, if the `now - lastFailure <= failureResetInterval`, we increment the `numFailures` for this particular peer and set the `lastFailure` to `now`. - Otherwise, we set `lastFailure` to `now` and set `numFailures` to 1. - Once the value for `numFailures` for a peer reaches `maxAllowedFailures`, the peer is disconnected from and banned. + Whenever a transaction fails, if the `now - lastFailure <= failureResetInterval`, we increment the `numFailures` for this particular peer and set the `lastFailure` to `now`. + Otherwise, we set `lastFailure` to `now` and set `numFailures` to 1. + Once the value for `numFailures` for a peer reaches `maxAllowedFailures`, the peer is disconnected from and banned. The reason for this logic is as follows: We deem it acceptable if every now and then a peer sends us an invalid transaction. - But if this happens very frequently, then this behaviour can be considered as spamming and we want to disconnect from the peer. - + But if this happens very frequently, then this behaviour can be considered as spamming and we want to disconnect from the peer. + **Discussion** - The problem with supporting this scenario is the definition of the above mentioned parameters. It is very hard to estimate, at the CometBFT level, what these parameters should be. A possible solution is - to allow the application to set these parameters. What is unclear, how will the application know that these parameters are not well set if, due to a bug or network problems, transactions start to fail? + The problem with supporting this scenario is the definition of the above mentioned parameters. It is very hard to estimate, at the CometBFT level, what these parameters should be. A possible solution is + to allow the application to set these parameters. What is unclear, how will the application know that these parameters are not well set if, due to a bug or network problems, transactions start to fail? The network could end up with all nodes banning everyone. How would an application developer know to debug this, what to look for? A possible solution is to ban peers temporarily. In addition to the question on how long is temporarily, setting specific time limits for banning on a peer basis @@ -160,29 +160,29 @@ is currently not supported by the p2p layer. *Banning a peer in case of duplicate transactions* -Currently, a peer can send the same valid (or invalid) transaction [multiple times](https://github.com/cometbft/cometbft/blob/ff0f98892f24aac11e46aeff2b6d2c0ad816701a/mempool/v0/clist_mempool.go#L247). Peers do not -gossip transactions to peers that have sent them that same transaction. But there is no check on whether +Currently, a peer can send the same valid (or invalid) transaction [multiple times](https://github.com/cometbft/cometbft/blob/ff0f98892f24aac11e46aeff2b6d2c0ad816701a/mempool/v0/clist_mempool.go#L247). Peers do not +gossip transactions to peers that have sent them that same transaction. But there is no check on whether a node has already sent the same transaction to this peer before. There is also no check whether the transaction that is being gossiped is currently valid or not (assuming that invalid transactions could become valid). -The transaction broadcast logic simply loops through the mempool and tries to send the transactions currently in the pool. +The transaction broadcast logic simply loops through the mempool and tries to send the transactions currently in the pool. -If we want to ban peers based on duplicate transactions, we should either add additional checks for the cases above, or -not ban peers for this behaviour at the moment. It would be useful to gather metrics on how often a peer gossips the same -transaction and whether this is cause of significant traffic. +If we want to ban peers based on duplicate transactions, we should either add additional checks for the cases above, or +not ban peers for this behaviour at the moment. It would be useful to gather metrics on how often a peer gossips the same +transaction and whether this is cause of significant traffic. #### **Banning for sending *never-valid* transactions** -If a transaction fails since it could never have been valid, `CheckTx` returns a `ResponseCheckTx.code` -value greater than 1. In this case, the peer should be disconnected from and banned immediately without keeping count on how often -this has happened. +If a transaction fails since it could never have been valid, `CheckTx` returns a `ResponseCheckTx.code` +value greater than 1. In this case, the peer should be disconnected from and banned immediately without keeping count on how often +this has happened. -The question is whether this transaction should be kept track of in the cache? We can still store it in +The question is whether this transaction should be kept track of in the cache? We can still store it in the cache so that we don't run `CheckTx` on it again, but if this peer is immediately banned, maybe there is no need to store its information. Now, if we want to differentiate further reasons of why this transaction is sent to a node (whether it is a sign of malice or not), -we might need more information on the actual reason for rejection. This could be done by an additional set of response codes provided by the application. +we might need more information on the actual reason for rejection. This could be done by an additional set of response codes provided by the application. ### 2. Choosing the peer to ban @@ -190,20 +190,20 @@ Each transaction gossiped contains the ID of the peer that sent that transaction a node saves the peer ID of the peer(s) that have sent it. As each peer had to have run `CheckTx` on this transaction before adding it to its own mempool, we can assume this peer can be held accountable for the validity of transactions it gossips. Invalid transactions are kept only in the mempool -cache and thus not gossiped. +cache and thus not gossiped. As nodes have to complete a cryptographic handshake at the p2p layer, CometBFT guarantees that a malicious peer -cannot lie about who the sender of the transaction is. +cannot lie about who the sender of the transaction is. *Transactions received from users* -For transactions submitted via `broadcastTxCommit`, the `SenderID` field is empty. +For transactions submitted via `broadcastTxCommit`, the `SenderID` field is empty. **Question** Do we have mechanisms in place to handle cases when `broadcastTxCommit` submits failing transactions (can this be a form of attack)? **From PR discussion** -At the moment there is no particular defense mechanism beyond rate limiting as for any RPC endpoint (which is not done internally by CometBFT). -An alternative would be to indeed internally make sure we do not get spammed with bad transaction using this endpoint. +At the moment there is no particular defense mechanism beyond rate limiting as for any RPC endpoint (which is not done internally by CometBFT). +An alternative would be to indeed internally make sure we do not get spammed with bad transaction using this endpoint. ### 3. Attack scenarios @@ -211,22 +211,22 @@ While an attack by simply banning peers on failing `CheckTx` is hard to imagine, Should we keep transactions that could never have been valid in the cache? Assuming that receiving such transactions is rare, and the peer that sent them is banned, do we need to occupy space in the mempool cache with these transactions? -- What if nodes run different versions of CometBFT and banning is not supported in one of the versions? +- What if nodes run different versions of CometBFT and banning is not supported in one of the versions? + +- Reserving response codes can be problematic for existing applications that may have reserved these codes for internal purposes withtou being aware that this causes a ban now. -- Reserving response codes can be problematic for existing applications that may have reserved these codes for internal purposes withtou being aware that this causes a ban now. - ## Implementation considerations **Indicating a new type of `CheckTx` failure** -The initial proposal is to reserve a special response code to indicate that the transaction could never have been valid. +The initial proposal is to reserve a special response code to indicate that the transaction could never have been valid. Due to concerns of this being a breaking change for applications that have already reserved this code for internal -purposes, there is an alternative implementation: expanding `ResponseCheckTx` with an additional field. +purposes, there is an alternative implementation: expanding `ResponseCheckTx` with an additional field. This field `neverValidTx` would be `false` by default. If a transaction could never have been valid, -in addition to indicating this with a non-zero response code from `CheckTx`, the application would set this field value. +in addition to indicating this with a non-zero response code from `CheckTx`, the application would set this field value. -Another proposal is to expand this, by allowing the application to explicitly instruct CometBFT on whether to ban a peer or not. +Another proposal is to expand this, by allowing the application to explicitly instruct CometBFT on whether to ban a peer or not. This requires adding yet another field to `CheckTx`: `banPeer`. The field can have the following values: - `0`(default): do not ban peer - `1`: decrement peer reputation (if such a mechanism exists in the p2p layer) @@ -234,23 +234,23 @@ This requires adding yet another field to `CheckTx`: `banPeer`. The field can ha **Adding support for peer banning** -When a transaction fails `CheckTx`, it is not stored in the mempool but **can** be stored in the cache. If it is in the cache, it cannot be resubmitted again (as it will be discovered in the cache and not checked again). These two scenarios require a different implementation of banning in case `CheckTx` failed. +When a transaction fails `CheckTx`, it is not stored in the mempool but **can** be stored in the cache. If it is in the cache, it cannot be resubmitted again (as it will be discovered in the cache and not checked again). These two scenarios require a different implementation of banning in case `CheckTx` failed. -In both cases we need to keep track of the peers that sent invalid transactions. If invalid transactions are cached, -we also need to keep track of the `CheckTx` response code for each transaction. Currently the `ResponseCheckTx` code is checked in `resCbFirstTime` of the mempool. -If invalid transactions are kept in the cache, the check is ran only when a transaction is -seen for the first time. Afterwards, the transaction is cached, to avoid running `CheckTx` on transactions already checked. +In both cases we need to keep track of the peers that sent invalid transactions. If invalid transactions are cached, +we also need to keep track of the `CheckTx` response code for each transaction. Currently the `ResponseCheckTx` code is checked in `resCbFirstTime` of the mempool. +If invalid transactions are kept in the cache, the check is ran only when a transaction is +seen for the first time. Afterwards, the transaction is cached, to avoid running `CheckTx` on transactions already checked. Thus when a transaction is received from a peer, if it is in the cache, `CheckTx` is not ran again, but the peers' ID is added to the list of peers who sent this particular transaction. -These transactions are rechecked once a block is committed to verify that they are still valid. +These transactions are rechecked once a block is committed to verify that they are still valid. -If invalid transactions are not kept in the cache, they can be resubmitted multiple times, and `CheckTx` will be executed on them upon submission. +If invalid transactions are not kept in the cache, they can be resubmitted multiple times, and `CheckTx` will be executed on them upon submission. Therefore we do not need to remember the previous response codes for these transactions. In summary, if we want to support banning peers based on the frequency with which they submit invalid transactions, we need to have **additional datastructures**: 1. One to keep track of past invalid transactions 2. A datastructure to differentiate between valid and invalid *cached* transactions. If the `KeepInvalidTxsInCache` configuration parameter is not set, this datastructure - is not needed. + is not needed. We propose two ways to implement peer banning based on the result of `CheckTx`: @@ -261,7 +261,7 @@ We propose two ways to implement peer banning based on the result of `CheckTx`: **Peer banning when transactions are received** -If a transaction fails `CheckTx` the +If a transaction fails `CheckTx` the [first time it is seen](https://github.com/cometbft/cometbft/blob/ff0f98892f24aac11e46aeff2b6d2c0ad816701a/mempool/v0/clist_mempool.go#L409), the peer can be banned right there: @@ -292,11 +292,11 @@ if (r.CheckTx.Code == abci.CodeTypeOK) && postCheckErr == nil { } } -``` +``` The `KeepInvalidTxsInCache` configuration parameter defines whether an invalid transaction stays in cache. For *never-valid* transactions, we could apply a different approach based on what we deem to be the bigger gain: - As we do not expect to receive frequently and from many peers, and we ban the peer that sent it immediately, we do not store it in the cache to save space. This would mean -that if we did see it again, we'd ran `CheckTx` on it again. +that if we did see it again, we'd ran `CheckTx` on it again. ```golang if !mem.config.KeepInvalidTxsInCache || r.CheckTx.Code == abci.NeverValid { @@ -305,20 +305,20 @@ if !mem.config.KeepInvalidTxsInCache || r.CheckTx.Code == abci.NeverValid { } ``` -- We do keep it in the cache as long as possible to avoid running `CheckTX` on it because we know, for sure, that it will never be valid. As it is rare enough, it -might not take that much space. In this case though, as we ban the sending peer immediately, we can save space by not storing peer information for this transaction. +- We do keep it in the cache as long as possible to avoid running `CheckTX` on it because we know, for sure, that it will never be valid. As it is rare enough, it +might not take that much space. In this case though, as we ban the sending peer immediately, we can save space by not storing peer information for this transaction. The question is which one is more costly, doing `CheckTx` more then once, or keeping an extra entry in the cache? -As said, this code will [never be executed](https://github.com/cometbft/cometbft/blob/ff0f98892f24aac11e46aeff2b6d2c0ad816701a/mempool/v0/clist_mempool.go#L239) +As said, this code will [never be executed](https://github.com/cometbft/cometbft/blob/ff0f98892f24aac11e46aeff2b6d2c0ad816701a/mempool/v0/clist_mempool.go#L239) for transactions whose hash is found -in the cache. +in the cache. Instead of remembering the cached transactions, we could have had a valid/invalid bit per transaction within the cache. As transactions themselves do not store such information and we expect this scenario to be unlikely, instead of increasing the footprint of all transactions in the cache, -we opted to keep a map of transaction signature if the transaction is in the cache, but is invalid. Alternatively, the cache could keep two lists, one for valid, and one for invalid transactions. -This modifies the following pieces of code as follows (this is just a prototype and does not include +we opted to keep a map of transaction signature if the transaction is in the cache, but is invalid. Alternatively, the cache could keep two lists, one for valid, and one for invalid transactions. +This modifies the following pieces of code as follows (this is just a prototype and does not include some obvious sanity checks): ```golang @@ -359,7 +359,7 @@ if !mem.cache.Push(tx) { // if the transaction already exists in the cache // If transaction was invalid, we need to remember the peer information if _, ok := mem.cache.invalidCachedTx.Load(tx.Key); ok { - mem.banPeer(peerID) + mem.banPeer(peerID) } return mempool.ErrTxInCache } @@ -375,15 +375,15 @@ func (mem* ClistMempool) banPeer(peerID NodeID) { if val, ok := mem.peerFailureMap[peerID]; ok { lastFailureT := val.lastFailure numFails = val.numFails - // if the failure was recent enough, update the number of failures and + // if the failure was recent enough, update the number of failures and // ban peer if applicable if time.Since(lastFailureT) <= failureResetInterval { if numFails == maxAllowedFailures - 1 { - // Send Ban request to p2p + // Send Ban request to p2p } } } - // Update the time of the last failure + // Update the time of the last failure mem.peerFailureMap[peerID] = { time.Now(), numFailures + 1} } ``` @@ -396,85 +396,85 @@ As it is the mempool **reactor** that has access to the p2p layer, not the actua **Implementing peer banning on recheck** -Currently the recheck logic confirmes whether once **valid** transactions, -, where `ResponseCheckTx.code == 0`, are still valid. +Currently the recheck logic confirmes whether once **valid** transactions, +, where `ResponseCheckTx.code == 0`, are still valid. -As this logic loops through the transactions in any case, we can leverage it to check whether we can ban peers. +As this logic loops through the transactions in any case, we can leverage it to check whether we can ban peers. However, this approach has several downsides: -- It is not timely enough. Recheck is executed after a block is committed, leaving room for a bad peer to send -us transactions the entire time between two blocks. -- If we want to keep track of when peers sent us a traansaction and punish them only if the misbehaviour happens -frequently enough, this approach makes it hard to keep track of when exactly was a transaction submitted. -- Rechecking if optional and node operators can disable it. +- It is not timely enough. Recheck is executed after a block is committed, leaving room for a bad peer to send +us transactions the entire time between two blocks. +- If we want to keep track of when peers sent us a traansaction and punish them only if the misbehaviour happens +frequently enough, this approach makes it hard to keep track of when exactly was a transaction submitted. +- Rechecking if optional and node operators can disable it. - Furthermore, rechecking is a node local configuration parameter. This means that, some nodes might be performing this check, - while others will be unaware of this. + while others will be unaware of this. On the plus side this would avoid adding new logic to the mempool caching mechanism and keeping additional information about transaction validity. But we would still have to keep the information on peers and the frequency at which they send us bad transactions. -Transactions that became invalid on recheck should not be cause for peer banning as they have not been gossiped as invalid transactions. +Transactions that became invalid on recheck should not be cause for peer banning as they have not been gossiped as invalid transactions. #### `PreCheck` and`PostCheck` -The `PreCheck` and `PostCheck` functions are optional functions that can be executed before or after `CheckTx`. -Following the design outlined in this RFC, their responses are not considered for banning. +The `PreCheck` and `PostCheck` functions are optional functions that can be executed before or after `CheckTx`. +Following the design outlined in this RFC, their responses are not considered for banning. #### Checks outside `CheckTx` -There are a number of checks that the mempool performs on the transaction, that are not part of `CheckTx` itself. +There are a number of checks that the mempool performs on the transaction, that are not part of `CheckTx` itself. Those checks, have been mentioned in the user issues described at the beginning of this document: - Transaction size - Proto checks - Receiving unknown messages via the mempool channel -The previous code snippets do not incroporate these in peer banning. If we adopt those as valid reasons for banning, we should put the corresponding logic in place. +The previous code snippets do not incroporate these in peer banning. If we adopt those as valid reasons for banning, we should put the corresponding logic in place. ### Impacted mempool functionalities -- Mempool caching: remembering failed transactions and whether they come from banned peers; Removal of transactions from +- Mempool caching: remembering failed transactions and whether they come from banned peers; Removal of transactions from `invalidCachedTx` when a transaction is removed from cache. - Handling of transactions failing `CheckTx`: Keeping track of how often transactions from a particular peer have failed and banning them if the conditions for a ban are met. -### Impact on ABCI +### Impact on ABCI -- Introduction of new response codes for CheckTx. As previously noted, this might break existing applications if they reserved codes for internal purposes. +- Introduction of new response codes for CheckTx. As previously noted, this might break existing applications if they reserved codes for internal purposes. - Altering the specification to reflect this change ### Github discussion summary -The main concern that arose from the discussion on github is whether banning peers based on the return code of `CheckTx` -can lead to unwanted side effects, such as partitioning the network or influencing the behaviour of other nodes. +The main concern that arose from the discussion on github is whether banning peers based on the return code of `CheckTx` +can lead to unwanted side effects, such as partitioning the network or influencing the behaviour of other nodes. #### *Potential failure scenarios* -* Assume we have a network that is configured in such a way that there exists an overlay network, and a node can only influence its direct connections. +* Assume we have a network that is configured in such a way that there exists an overlay network, and a node can only influence its direct connections. The node can force a peer to disconnect from it forever if, say, it wanted to lower the number of ways it has of getting messages to the rest of the network. However, that could have already be done by just disconnecting or by dropping its messages. * A bug in `CheckTx`causes the rejection of all transactions and all nodes disconnect, how do we ensure the operator knows what has happened? * An attacker discovers a particular transaction that they know would be accepted, and therefore propagated, by >1/3 of the voting power on the network, - but rejected by the rest. This would result in halting the network for the period for which we blacklist "misconfigured" peers, - because >1/3 of the voting power would be blacklisted by the remaining peers. This means that if >1/3 of the voting power on a network has, - for example, a minimum transaction fee requirement much lower than the remaining nodes, and application developers return a `neverValidTx=true` + but rejected by the rest. This would result in halting the network for the period for which we blacklist "misconfigured" peers, + because >1/3 of the voting power would be blacklisted by the remaining peers. This means that if >1/3 of the voting power on a network has, + for example, a minimum transaction fee requirement much lower than the remaining nodes, and application developers return a `neverValidTx=true` value from `CheckTx` here, they could halt their network. #### *Decisions* -The uncertainties are higher in the case of banning based on the *frequency* of the failures. This option has therefore been **dismissed**. +The uncertainties are higher in the case of banning based on the *frequency* of the failures. This option has therefore been **dismissed**. As for the banning based on the return code from the application, due to the lack of strong use cases and potential unwanted side-effects, -it will not be implemented at the moment of writing the final version of this RFC (March 2023). +it will not be implemented at the moment of writing the final version of this RFC (March 2023). An alternative is being proposed at the moment due to feedback we received when debugging the Gaia issue mentioned above. Namely, they found that having these peers banned or even a log message about this failure would have significantly shortened the debugging -time. +time. -Additionally, as input from Osmosis, we got a potential security-related use case for the implementation of banning. +Additionally, as input from Osmosis, we got a potential security-related use case for the implementation of banning. It was therefore proposed to first implement a log message that the transaction could never have been valid, and even send this message to the sender of the transaction, warning the node that it sent a transaction that failed `CheckTx`. But this should not be sent on every `CheckTx` failure as it would create a lot of noise (we mentioned the valid reasons for `CheckTx` to failures). We would indeed require adding a special code and/or the `neverValidTx` flag @@ -482,16 +482,16 @@ to `ResponseCheckTx`, and logging this warning only if the application sets thes This would facilitate debugging and pinpointing the problem for operators of the nodes receiving these warnings. -Then, once we progress with the p2p specification and understand all possible implications of banning, actual peer banning can be implemented. +Then, once we progress with the p2p specification and understand all possible implications of banning, actual peer banning can be implemented. #### *Discussion on minor implementation details* -For completeness, and to make sure the information is not lost, there were a few discussions on minor implementation details. +For completeness, and to make sure the information is not lost, there were a few discussions on minor implementation details. *Keeping transactions failing `CheckTx` with a special code in the cache* -Without any change to the current logic, these transactions are kept in the cache, as long as they are not evicted. -Users argued for these transactions to be rare enough, that they can safely be discarded in the case a peer is actually banned after sending them. +Without any change to the current logic, these transactions are kept in the cache, as long as they are not evicted. +Users argued for these transactions to be rare enough, that they can safely be discarded in the case a peer is actually banned after sending them. *Banning based on IP or nodeID* @@ -506,7 +506,7 @@ Other than avoiding relying solely on the response code values, there are no imm - Most of the relevant links are in the [existing issues and concerns section](#existing-issues-and-concerns) -- [`CheckTx` function description](./../../spec/abci/abci%2B%2B_methods.md#checktx) +- [`CheckTx` function description](../../../spec/abci/abci++_methods.md#checktx) - Github discussions on this RFC: - [CometBFT repo - PR \#78](https://github.com/cometbft/cometbft/pull/78) diff --git a/docs/rfc/rfc-102-rust-gen-builders.md b/docs/references/rfc/rfc-102-rust-gen-builders.md similarity index 100% rename from docs/rfc/rfc-102-rust-gen-builders.md rename to docs/references/rfc/rfc-102-rust-gen-builders.md diff --git a/docs/rfc/rfc-103-incoming-txs-when-catching-up.md b/docs/references/rfc/rfc-103-incoming-txs-when-catching-up.md similarity index 97% rename from docs/rfc/rfc-103-incoming-txs-when-catching-up.md rename to docs/references/rfc/rfc-103-incoming-txs-when-catching-up.md index af641a7b3a1..161d0ff4990 100644 --- a/docs/rfc/rfc-103-incoming-txs-when-catching-up.md +++ b/docs/references/rfc/rfc-103-incoming-txs-when-catching-up.md @@ -79,7 +79,7 @@ transaction is invalid. This can occur in three cases. 1. The first time a transaction is received and then rejected by `CheckTx`. 2. When the block executor [updates][update] the mempool, right after finalizing and committing a block: if there was an error while executing a transaction - against the application, then it is removed from the cache. + against the application, then it is removed from the cache. 3. When all the transactions in the mempool need to be rechecked after a new block has been delivered to the application. Each transaction will be validated again with `CheckTx` and removed from the cache if deemed invalid. @@ -148,10 +148,10 @@ if peerState.GetHeight() < memTx.Height()-1 { continue } ``` -where: +where: - `peerState` is the local state of the peer (updated with the information received by the consensus reactor in `PeerState.ApplyNewRoundStepMessage` - messages), + messages), - `memTx.Height()` is the height at which transaction `memTx.tx` was validated (set during the handling of `CheckTx` responses), and - `PeerCatchupSleepIntervalMS` is fixed to `100`. @@ -174,14 +174,14 @@ shows the results of an experiment with four interconnected nodes. On the left we see the collected metrics when we run the nodes without the optimization. On the right we see the results of running the nodes with the optimization, that is, without modifying the code. -![rfc-103-comparison](./images/rfc-103-optimization-comparison.png) The node in +![rfc-103-comparison](images/rfc-103-optimization-comparison.png) The node in orange called _validator04_ joins the network at around height 100 and starts performing block sync. In the graph at the bottom we can see the height of all nodes and in particular how this node starts from height 0 and catches up with the other nodes. Also we can observe that, when the optimization is disabled (left side), while the orange node is catching up, both its mempool size (top graph) and the number of rejected transactions (middle graph) increases -significantly compared to the optimizated code (right side). +significantly compared to the optimizated code (right side). __Decision__ The results presented above indicate that the optimization is effectively improving the system's performance and should be kept for now. In diff --git a/docs/rfc/rfc-104-actor-model.md b/docs/references/rfc/rfc-104-actor-model.md similarity index 100% rename from docs/rfc/rfc-104-actor-model.md rename to docs/references/rfc/rfc-104-actor-model.md diff --git a/docs/rfc/rfc-105-non-det-process-proposal.md b/docs/references/rfc/rfc-105-non-det-process-proposal.md similarity index 100% rename from docs/rfc/rfc-105-non-det-process-proposal.md rename to docs/references/rfc/rfc-105-non-det-process-proposal.md diff --git a/docs/rfc/rfc-106-separate-stateful-methods.md b/docs/references/rfc/rfc-106-separate-stateful-methods.md similarity index 100% rename from docs/rfc/rfc-106-separate-stateful-methods.md rename to docs/references/rfc/rfc-106-separate-stateful-methods.md diff --git a/docs/rfc/rfc-107-event-observer.md b/docs/references/rfc/rfc-107-event-observer.md similarity index 99% rename from docs/rfc/rfc-107-event-observer.md rename to docs/references/rfc/rfc-107-event-observer.md index 4e1a77c59fe..98599d02443 100644 --- a/docs/rfc/rfc-107-event-observer.md +++ b/docs/references/rfc/rfc-107-event-observer.md @@ -229,7 +229,7 @@ The drawbacks of the proposed approach include: still possible depending on how observers are implemented [\#1055]: https://github.com/cometbft/cometbft/issues/1055 -[RFC 104]: ./rfc-104-actor-model.md +[RFC 104]: rfc-104-actor-model.md [Actor]: https://en.wikipedia.org/wiki/Actor_model [Observer Pattern]: https://en.wikipedia.org/wiki/Observer_pattern [`EventBus`]: https://github.com/cometbft/cometbft/blob/b23ef56f8e6d8a7015a7f816a61f2e53b0b07b0d/types/event_bus.go#L33 diff --git a/docs/rfc/rfc-template.md b/docs/references/rfc/rfc-template.md similarity index 100% rename from docs/rfc/rfc-template.md rename to docs/references/rfc/rfc-template.md diff --git a/docs/references/rfc/tendermint-core/README.md b/docs/references/rfc/tendermint-core/README.md new file mode 100644 index 00000000000..014f04d9ad8 --- /dev/null +++ b/docs/references/rfc/tendermint-core/README.md @@ -0,0 +1,42 @@ +--- +order: 1 +parent: + order: false +--- + +# Tendermint Core Requests for Comments + +This document serves as a historical reference for all RFCs that were logged +during the development of Tendermint Core. + +This list is frozen as-is, and new RFCs should be added [here](../). + +## Table of Contents + +- [RFC-000: P2P Roadmap](rfc-000-p2p-roadmap.rst) +- [RFC-001: Storage Engines](rfc-001-storage-engine.rst) +- [RFC-002: Interprocess Communication](rfc-002-ipc-ecosystem.md) +- [RFC-003: Performance Taxonomy](rfc-003-performance-questions.md) +- [RFC-004: E2E Test Framework Enhancements](rfc-004-e2e-framework.rst) +- [RFC-005: Event System](rfc-005-event-system.rst) +- [RFC-006: Event Subscription](rfc-006-event-subscription.md) +- [RFC-007: Deterministic Proto Byte Serialization](rfc-007-deterministic-proto-bytes.md) +- [RFC-008: Don't Panic](rfc-008-do-not-panic.md) +- [RFC-009: Consensus Parameter Upgrades](rfc-009-consensus-parameter-upgrades.md) +- [RFC-010: P2P Light Client](rfc-010-p2p-light-client.rst) +- [RFC-011: Delete Gas](rfc-011-delete-gas.md) +- [RFC-012: Event Indexing Revisited](rfc-012-custom-indexing.md) +- [RFC-013: ABCI++](rfc-013-abci++.md) +- [RFC-014: Semantic Versioning](rfc-014-semantic-versioning.md) +- [RFC-015: ABCI++ Tx Mutation](rfc-015-abci++-tx-mutation.md) +- [RFC-016: Node Architecture](rfc-016-node-architecture.md) +- [RFC-017: ABCI++ Vote Extension Propagation](rfc-017-abci++-vote-extension-propag.md) +- [RFC-018: BLS Signature Aggregation Exploration](rfc-018-bls-agg-exploration.md) +- [RFC-019: Configuration File Versioning](rfc-019-config-version.md) +- [RFC-020: Onboarding Projects](rfc-020-onboarding-projects.rst) +- [RFC-021: The Future of the Socket Protocol](rfc-021-socket-protocol.md) +- [RFC-023: Semi-permanent Testnet](rfc-023-semi-permanent-testnet.md) +- [RFC-024: Block Structure Consolidation](rfc-024-block-structure-consolidation.md) +- [RFC-025: Application Defined Transaction Storage](rfc-025-support-app-side-mempool.md) +- [RFC-026: Banning peers based on ResponseCheckTx](rfc-026-p2p-bad-peers-checktx.md) +- [RFC-027: P2P Message Bandwidth Report](rfc-027-p2p-message-bandwidth-report.md) diff --git a/docs/rfc/tendermint-core/images/abci++.png b/docs/references/rfc/tendermint-core/images/abci++.png similarity index 100% rename from docs/rfc/tendermint-core/images/abci++.png rename to docs/references/rfc/tendermint-core/images/abci++.png diff --git a/docs/rfc/tendermint-core/images/abci.png b/docs/references/rfc/tendermint-core/images/abci.png similarity index 100% rename from docs/rfc/tendermint-core/images/abci.png rename to docs/references/rfc/tendermint-core/images/abci.png diff --git a/docs/rfc/tendermint-core/images/node-dependency-tree.svg b/docs/references/rfc/tendermint-core/images/node-dependency-tree.svg similarity index 100% rename from docs/rfc/tendermint-core/images/node-dependency-tree.svg rename to docs/references/rfc/tendermint-core/images/node-dependency-tree.svg diff --git a/docs/rfc/tendermint-core/images/receive-rate-all.png b/docs/references/rfc/tendermint-core/images/receive-rate-all.png similarity index 100% rename from docs/rfc/tendermint-core/images/receive-rate-all.png rename to docs/references/rfc/tendermint-core/images/receive-rate-all.png diff --git a/docs/rfc/tendermint-core/images/send-rate-all.png b/docs/references/rfc/tendermint-core/images/send-rate-all.png similarity index 100% rename from docs/rfc/tendermint-core/images/send-rate-all.png rename to docs/references/rfc/tendermint-core/images/send-rate-all.png diff --git a/docs/rfc/tendermint-core/images/top-3-percent-receive.png b/docs/references/rfc/tendermint-core/images/top-3-percent-receive.png similarity index 100% rename from docs/rfc/tendermint-core/images/top-3-percent-receive.png rename to docs/references/rfc/tendermint-core/images/top-3-percent-receive.png diff --git a/docs/rfc/tendermint-core/images/top-3-percent-send.png b/docs/references/rfc/tendermint-core/images/top-3-percent-send.png similarity index 100% rename from docs/rfc/tendermint-core/images/top-3-percent-send.png rename to docs/references/rfc/tendermint-core/images/top-3-percent-send.png diff --git a/docs/rfc/tendermint-core/rfc-000-p2p-roadmap.rst b/docs/references/rfc/tendermint-core/rfc-000-p2p-roadmap.rst similarity index 100% rename from docs/rfc/tendermint-core/rfc-000-p2p-roadmap.rst rename to docs/references/rfc/tendermint-core/rfc-000-p2p-roadmap.rst diff --git a/docs/rfc/tendermint-core/rfc-001-storage-engine.rst b/docs/references/rfc/tendermint-core/rfc-001-storage-engine.rst similarity index 100% rename from docs/rfc/tendermint-core/rfc-001-storage-engine.rst rename to docs/references/rfc/tendermint-core/rfc-001-storage-engine.rst diff --git a/docs/rfc/tendermint-core/rfc-002-ipc-ecosystem.md b/docs/references/rfc/tendermint-core/rfc-002-ipc-ecosystem.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-002-ipc-ecosystem.md rename to docs/references/rfc/tendermint-core/rfc-002-ipc-ecosystem.md diff --git a/docs/rfc/tendermint-core/rfc-003-performance-questions.md b/docs/references/rfc/tendermint-core/rfc-003-performance-questions.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-003-performance-questions.md rename to docs/references/rfc/tendermint-core/rfc-003-performance-questions.md diff --git a/docs/rfc/tendermint-core/rfc-004-e2e-framework.rst b/docs/references/rfc/tendermint-core/rfc-004-e2e-framework.rst similarity index 100% rename from docs/rfc/tendermint-core/rfc-004-e2e-framework.rst rename to docs/references/rfc/tendermint-core/rfc-004-e2e-framework.rst diff --git a/docs/rfc/tendermint-core/rfc-005-event-system.rst b/docs/references/rfc/tendermint-core/rfc-005-event-system.rst similarity index 100% rename from docs/rfc/tendermint-core/rfc-005-event-system.rst rename to docs/references/rfc/tendermint-core/rfc-005-event-system.rst diff --git a/docs/rfc/tendermint-core/rfc-006-event-subscription.md b/docs/references/rfc/tendermint-core/rfc-006-event-subscription.md similarity index 99% rename from docs/rfc/tendermint-core/rfc-006-event-subscription.md rename to docs/references/rfc/tendermint-core/rfc-006-event-subscription.md index 0e03c119120..1da41520268 100644 --- a/docs/rfc/tendermint-core/rfc-006-event-subscription.md +++ b/docs/references/rfc/tendermint-core/rfc-006-event-subscription.md @@ -196,8 +196,8 @@ mutually exclusive. [rpc-service]: https://docs.tendermint.com/v0.34/rpc/ [rpc-methods]: https://github.com/tendermint/tendermint/blob/main/rpc/core/routes.go#L12 -[events]: ./rfc-005-event-system.rst -[rpc-transport]: ./rfc-002-ipc-ecosystem.md#rpc-transport +[events]: rfc-005-event-system.rst +[rpc-transport]: rfc-002-ipc-ecosystem.md#rpc-transport [ws]: https://datatracker.ietf.org/doc/html/rfc6455 [json-response]: https://www.jsonrpc.org/specification#response_object [json-notify]: https://www.jsonrpc.org/specification#notification diff --git a/docs/rfc/tendermint-core/rfc-007-deterministic-proto-bytes.md b/docs/references/rfc/tendermint-core/rfc-007-deterministic-proto-bytes.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-007-deterministic-proto-bytes.md rename to docs/references/rfc/tendermint-core/rfc-007-deterministic-proto-bytes.md diff --git a/docs/rfc/tendermint-core/rfc-008-do-not-panic.md b/docs/references/rfc/tendermint-core/rfc-008-do-not-panic.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-008-do-not-panic.md rename to docs/references/rfc/tendermint-core/rfc-008-do-not-panic.md diff --git a/docs/rfc/tendermint-core/rfc-009-consensus-parameter-upgrades.md b/docs/references/rfc/tendermint-core/rfc-009-consensus-parameter-upgrades.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-009-consensus-parameter-upgrades.md rename to docs/references/rfc/tendermint-core/rfc-009-consensus-parameter-upgrades.md diff --git a/docs/rfc/tendermint-core/rfc-010-p2p-light-client.rst b/docs/references/rfc/tendermint-core/rfc-010-p2p-light-client.rst similarity index 100% rename from docs/rfc/tendermint-core/rfc-010-p2p-light-client.rst rename to docs/references/rfc/tendermint-core/rfc-010-p2p-light-client.rst diff --git a/docs/rfc/tendermint-core/rfc-011-delete-gas.md b/docs/references/rfc/tendermint-core/rfc-011-delete-gas.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-011-delete-gas.md rename to docs/references/rfc/tendermint-core/rfc-011-delete-gas.md diff --git a/docs/rfc/tendermint-core/rfc-012-custom-indexing.md b/docs/references/rfc/tendermint-core/rfc-012-custom-indexing.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-012-custom-indexing.md rename to docs/references/rfc/tendermint-core/rfc-012-custom-indexing.md diff --git a/docs/rfc/tendermint-core/rfc-013-abci++.md b/docs/references/rfc/tendermint-core/rfc-013-abci++.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-013-abci++.md rename to docs/references/rfc/tendermint-core/rfc-013-abci++.md diff --git a/docs/rfc/tendermint-core/rfc-014-semantic-versioning.md b/docs/references/rfc/tendermint-core/rfc-014-semantic-versioning.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-014-semantic-versioning.md rename to docs/references/rfc/tendermint-core/rfc-014-semantic-versioning.md diff --git a/docs/rfc/tendermint-core/rfc-015-abci++-tx-mutation.md b/docs/references/rfc/tendermint-core/rfc-015-abci++-tx-mutation.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-015-abci++-tx-mutation.md rename to docs/references/rfc/tendermint-core/rfc-015-abci++-tx-mutation.md diff --git a/docs/rfc/tendermint-core/rfc-016-node-architecture.md b/docs/references/rfc/tendermint-core/rfc-016-node-architecture.md similarity index 95% rename from docs/rfc/tendermint-core/rfc-016-node-architecture.md rename to docs/references/rfc/tendermint-core/rfc-016-node-architecture.md index 258492ff847..b43e16237f2 100644 --- a/docs/rfc/tendermint-core/rfc-016-node-architecture.md +++ b/docs/references/rfc/tendermint-core/rfc-016-node-architecture.md @@ -19,7 +19,7 @@ The following is a list of points of discussion around the architecture of the n The node object is currently stuffed with every component that possibly exists within Tendermint. In the constructor, all objects are built and interlaid with one another in some awkward dance. My guiding principle is that the node should only be made up of the components that it wants to have direct control of throughout its life. The node is a service which currently has the purpose of starting other services up in a particular order and stopping them all when commanded to do so. However, there are many services which are not direct dependents i.e. the mempool and evidence services should only be working when the consensus service is running. I propose to form more of a hierarchical structure of dependents which forces us to be clear about the relations that one component has to the other. More concretely, I propose the following dependency tree: -![node dependency tree](./images/node-dependency-tree.svg) +![node dependency tree](images/node-dependency-tree.svg) Many of the further discussion topics circle back to this representation of the node. @@ -48,7 +48,7 @@ The block executor is an important component that is currently used by both cons ### The Interprocess communication systems: RPC, P2P, ABCI, and Events The schematic supplied above shows the relations between the different services, the node, the block executor, and the storage layer. Represented as colored dots are the components responsible for different roles of interprocess communication (IPC). These components permeate throughout the code base, seeping into most services. What can provide powerful functionality on one hand can also become a twisted vine, creating messy corner cases and convoluting the protocols themselves. A lot of the thinking around -how we want our IPC systems to function has been summarised in this [RFC](./rfc-002-ipc-ecosystem.md). In this section, I'd like to focus the reader on the relation between the IPC and the node structure. An issue that has frequently risen is that the RPC has control of the components where it strikes me as being more logical for the component to dictate the information that is emitted/available and the knobs it wishes to expose. The RPC is also inextricably tied to the node instance and has situations where it is passed pointers directly to the storage engine and other components. +how we want our IPC systems to function has been summarised in this [RFC](rfc-002-ipc-ecosystem.md). In this section, I'd like to focus the reader on the relation between the IPC and the node structure. An issue that has frequently risen is that the RPC has control of the components where it strikes me as being more logical for the component to dictate the information that is emitted/available and the knobs it wishes to expose. The RPC is also inextricably tied to the node instance and has situations where it is passed pointers directly to the storage engine and other components. I am currently convinced of the approach that the p2p layer takes and would like to see other IPC components follow suit. This would mean that the RPC and events system would be constructed in the node yet would pass the adequate methods to register endpoints and topics to the sub components. For example, diff --git a/docs/rfc/tendermint-core/rfc-017-abci++-vote-extension-propag.md b/docs/references/rfc/tendermint-core/rfc-017-abci++-vote-extension-propag.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-017-abci++-vote-extension-propag.md rename to docs/references/rfc/tendermint-core/rfc-017-abci++-vote-extension-propag.md diff --git a/docs/rfc/tendermint-core/rfc-018-bls-agg-exploration.md b/docs/references/rfc/tendermint-core/rfc-018-bls-agg-exploration.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-018-bls-agg-exploration.md rename to docs/references/rfc/tendermint-core/rfc-018-bls-agg-exploration.md diff --git a/docs/rfc/tendermint-core/rfc-019-config-version.md b/docs/references/rfc/tendermint-core/rfc-019-config-version.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-019-config-version.md rename to docs/references/rfc/tendermint-core/rfc-019-config-version.md diff --git a/docs/rfc/tendermint-core/rfc-020-onboarding-projects.rst b/docs/references/rfc/tendermint-core/rfc-020-onboarding-projects.rst similarity index 100% rename from docs/rfc/tendermint-core/rfc-020-onboarding-projects.rst rename to docs/references/rfc/tendermint-core/rfc-020-onboarding-projects.rst diff --git a/docs/rfc/tendermint-core/rfc-021-socket-protocol.md b/docs/references/rfc/tendermint-core/rfc-021-socket-protocol.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-021-socket-protocol.md rename to docs/references/rfc/tendermint-core/rfc-021-socket-protocol.md diff --git a/docs/rfc/tendermint-core/rfc-023-semi-permanent-testnet.md b/docs/references/rfc/tendermint-core/rfc-023-semi-permanent-testnet.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-023-semi-permanent-testnet.md rename to docs/references/rfc/tendermint-core/rfc-023-semi-permanent-testnet.md diff --git a/docs/rfc/tendermint-core/rfc-024-block-structure-consolidation.md b/docs/references/rfc/tendermint-core/rfc-024-block-structure-consolidation.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-024-block-structure-consolidation.md rename to docs/references/rfc/tendermint-core/rfc-024-block-structure-consolidation.md diff --git a/docs/rfc/tendermint-core/rfc-025-support-app-side-mempool.md b/docs/references/rfc/tendermint-core/rfc-025-support-app-side-mempool.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-025-support-app-side-mempool.md rename to docs/references/rfc/tendermint-core/rfc-025-support-app-side-mempool.md diff --git a/docs/rfc/tendermint-core/rfc-026-p2p-bad-peers-checktx.md b/docs/references/rfc/tendermint-core/rfc-026-p2p-bad-peers-checktx.md similarity index 100% rename from docs/rfc/tendermint-core/rfc-026-p2p-bad-peers-checktx.md rename to docs/references/rfc/tendermint-core/rfc-026-p2p-bad-peers-checktx.md diff --git a/docs/rfc/tendermint-core/rfc-027-p2p-message-bandwidth-report.md b/docs/references/rfc/tendermint-core/rfc-027-p2p-message-bandwidth-report.md similarity index 98% rename from docs/rfc/tendermint-core/rfc-027-p2p-message-bandwidth-report.md rename to docs/references/rfc/tendermint-core/rfc-027-p2p-message-bandwidth-report.md index eaa99cdef4a..19199f6af5c 100644 --- a/docs/rfc/tendermint-core/rfc-027-p2p-message-bandwidth-report.md +++ b/docs/references/rfc/tendermint-core/rfc-027-p2p-message-bandwidth-report.md @@ -54,25 +54,25 @@ The image below of p2p data collected from the Blockpane validator illustrate the total bandwidth consumption of these three message types. -#### Send: +#### Send: -##### Top 3 Percent: +##### Top 3 Percent: -![](./images/top-3-percent-send.png) +![](images/top-3-percent-send.png) -##### Rate For All Messages: +##### Rate For All Messages: -![](./images/send-rate-all.png) +![](images/send-rate-all.png) -#### Receive: +#### Receive: -##### Top 3 Percent: +##### Top 3 Percent: -![](./images/top-3-percent-receive.png) +![](images/top-3-percent-receive.png) -##### Rate For All Messages: +##### Rate For All Messages: -![](./images/receive-rate-all.png) +![](images/receive-rate-all.png) ### Investigation of Message Usage diff --git a/docs/rfc/tendermint-core/README.md b/docs/rfc/tendermint-core/README.md deleted file mode 100644 index 7258586a031..00000000000 --- a/docs/rfc/tendermint-core/README.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -order: 1 -parent: - order: false ---- - -# Tendermint Core Requests for Comments - -This document serves as a historical reference for all RFCs that were logged -during the development of Tendermint Core. - -This list is frozen as-is, and new RFCs should be added [here](../). - -## Table of Contents - -- [RFC-000: P2P Roadmap](./rfc-000-p2p-roadmap.rst) -- [RFC-001: Storage Engines](./rfc-001-storage-engine.rst) -- [RFC-002: Interprocess Communication](./rfc-002-ipc-ecosystem.md) -- [RFC-003: Performance Taxonomy](./rfc-003-performance-questions.md) -- [RFC-004: E2E Test Framework Enhancements](./rfc-004-e2e-framework.rst) -- [RFC-005: Event System](./rfc-005-event-system.rst) -- [RFC-006: Event Subscription](./rfc-006-event-subscription.md) -- [RFC-007: Deterministic Proto Byte Serialization](./rfc-007-deterministic-proto-bytes.md) -- [RFC-008: Don't Panic](./rfc-008-do-not-panic.md) -- [RFC-009: Consensus Parameter Upgrades](./rfc-009-consensus-parameter-upgrades.md) -- [RFC-010: P2P Light Client](./rfc-010-p2p-light-client.rst) -- [RFC-011: Delete Gas](./rfc-011-delete-gas.md) -- [RFC-012: Event Indexing Revisited](./rfc-012-custom-indexing.md) -- [RFC-013: ABCI++](./rfc-013-abci++.md) -- [RFC-014: Semantic Versioning](./rfc-014-semantic-versioning.md) -- [RFC-015: ABCI++ Tx Mutation](./rfc-015-abci++-tx-mutation.md) -- [RFC-016: Node Architecture](./rfc-016-node-architecture.md) -- [RFC-017: ABCI++ Vote Extension Propagation](./rfc-017-abci++-vote-extension-propag.md) -- [RFC-018: BLS Signature Aggregation Exploration](./rfc-018-bls-agg-exploration.md) -- [RFC-019: Configuration File Versioning](./rfc-019-config-version.md) -- [RFC-020: Onboarding Projects](./rfc-020-onboarding-projects.rst) -- [RFC-021: The Future of the Socket Protocol](./rfc-021-socket-protocol.md) -- [RFC-023: Semi-permanent Testnet](./rfc-023-semi-permanent-testnet.md) -- [RFC-024: Block Structure Consolidation](./rfc-024-block-structure-consolidation.md) -- [RFC-025: Application Defined Transaction Storage](./rfc-025-support-app-side-mempool.md) -- [RFC-026: Banning peers based on ResponseCheckTx](./rfc-026-p2p-bad-peers-checktx.md) -- [RFC-027: P2P Message Bandwidth Report](./rfc-027-p2p-message-bandwidth-report.md) diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index ba6aaee59e9..1de81698b51 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -8,14 +8,17 @@ parent: # Welcome to CometBFT Tutorials -Are you ready to explore the world of CometBFT, the cutting-edge consensus algorithm that's revolutionizing the field of distributed systems? You've come to the right place! Our CometBFT Tutorials provide the knowledge and hands-on experience you need to master this groundbreaking technology. +Are you ready to explore the world of CometBFT, the cutting-edge consensus algorithm that's revolutionizing the +field of distributed systems? You've come to the right place! Our CometBFT Tutorials provide the knowledge +and hands-on experience you need to master this groundbreaking technology. ## Why Choose CometBFT Tutorials? - Comprehensive Learning: Our tutorials cover everything from the basics of consensus algorithms to advanced topics in CometBFT, ensuring that both beginners and experts can benefit. - Hands-On Experience: We believe in learning by doing. Our tutorials include practical examples and exercises that allow you to implement CometBFT in real-world scenarios. - Up-to-date Content: We keep our tutorials up-to-date with the latest developments in CometBFT, ensuring that you have access to the most current information and best practices. - Get Started Today! + +## Get Started Today! Whether you're a chain developer, an integrator, an operator, or simply curious about distributed systems, our CometBFT Tutorials are the perfect resource to enhance your knowledge and skills. diff --git a/spec/abci/abci++_app_requirements.md b/spec/abci/abci++_app_requirements.md index 671f6c3b140..34f632f3976 100644 --- a/spec/abci/abci++_app_requirements.md +++ b/spec/abci/abci++_app_requirements.md @@ -14,7 +14,7 @@ title: Requirements for the Application - [Finalize Block](#finalizeblock) - [Commit](#commit) - [Candidate States](#candidate-states) - - [States and ABCI++ Connections](#states-and-abci%2B%2B-connections) + - [States and ABCI++ Connections](#states-and-abci%2B%2B-connections) - [Consensus Connection](#consensus-connection) - [Mempool Connection](#mempool-connection) - [Info/Query Connection](#infoquery-connection) @@ -589,7 +589,7 @@ These are the current consensus parameters (as of v0.37.x): 10. [TimeoutParams.Vote](#timeoutparamsvote) 11. [TimeoutParams.VoteDelta](#timeoutparamsvotedelta) 12. [TimeoutParams.Commit](#timeoutparamscommit) -13. [TimeoutParams.BypassCommitTimeout](#timeoutparamsbypasscommittimeout) +13. [TimeoutParams.BypassCommitTimeout](#timeoutparamsbypasscommittimeout) --> ##### BlockParams.MaxBytes @@ -898,33 +898,33 @@ implementation of ### Crash Recovery -CometBFT and the application are expected to crash together and there should not +CometBFT and the application are expected to crash together and there should not exist a scenario where the application has persisted state of a height greater than the latest height persisted by CometBFT. -In practice, persisting the state of a height consists of three steps, the last of which +In practice, persisting the state of a height consists of three steps, the last of which is the call to the application's `Commit` method, the only place where the application is expected to persist/commit its state. On startup (upon recovery), CometBFT calls the `Info` method on the Info Connection to get the latest committed state of the app. The app MUST return information consistent with the -last block for which it successfully completed `Commit`. +last block for which it successfully completed `Commit`. -The three steps performed before the state of a height is considered persisted are: +The three steps performed before the state of a height is considered persisted are: - The block is stored by CometBFT in the blockstore - CometBFT has stored the state returned by the application through `FinalizeBlockResponse` -- The application has committed its state within `Commit`. - +- The application has committed its state within `Commit`. + The following diagram depicts the order in which these events happen, and the corresponding ABCI functions that are called and executed by CometBFT and the application: -``` +``` APP: Execute block Persist application state / return ResultFinalizeBlock / - / / + / / Event: ------------- block_stored ------------ / ------------ state_stored --------------- / ----- app_persisted_state | / | / | -CometBFT: Decide --- Persist block -- Call FinalizeBlock - Persist results ---------- Call Commit -- +CometBFT: Decide --- Persist block -- Call FinalizeBlock - Persist results ---------- Call Commit -- on in the (txResults, validator Block block store updates...) @@ -932,26 +932,26 @@ CometBFT: Decide --- Persist block -- Call FinalizeBlock - Persist results ----- As these three steps are not atomic, we observe different cases based on which steps have been executed before the crash occurred -(we assume that at least `block_stored` has been executed, otherwise, there is no state persisted, +(we assume that at least `block_stored` has been executed, otherwise, there is no state persisted, and the operations for this height are repeated entirely): - `block_stored`: we replay `FinalizeBlock` and the steps afterwards. - `block_stored` and `state_stored`: As the app did not persist its state within `Commit`, we need to re-execute - `FinalizeBlock` to retrieve the results and compare them to the state stored by CometBFT within `state_stored`. + `FinalizeBlock` to retrieve the results and compare them to the state stored by CometBFT within `state_stored`. The expected case is that the states will match, otherwise CometBFT panics. -- `block_stored`, `state_stored`, `app_persisted_state`: we move on to the next height. +- `block_stored`, `state_stored`, `app_persisted_state`: we move on to the next height. Based on the sequence of these events, CometBFT will panic if any of the steps in the sequence happen out of order, -that is if: +that is if: - The application has persisted a block at a height higher than the blocked saved during `state_stored`. - The `block_stored` step persisted a block at a height smaller than the `state_stored` -- And the difference between the heights of the blocks persisted by `state_stored` and `block_stored` is more +- And the difference between the heights of the blocks persisted by `state_stored` and `block_stored` is more than 1 (this corresponds to a scenario where we stored two blocks in the block store but never persisted the state of the first block, which should never happen). -A special case is when a crash happens before the first block is committed - that is, after calling +A special case is when a crash happens before the first block is committed - that is, after calling `InitChain`. In that case, the application's state should still be at height 0 and thus `InitChain` -will be called again. +will be called again. ### State Sync @@ -1100,10 +1100,10 @@ from the genesis file and light client RPC servers. It also calls `Info` to veri Once the state machine has been restored and CometBFT has gathered this additional information, it transitions to consensus. As of ABCI 2.0, CometBFT ensures the necessary conditions -to switch are met [RFC-100](./../../docs/rfc/rfc-100-abci-vote-extension-propag.md#base-implementation-persist-and-propagate-extended-commit-history). -From the application's point of view, these operations are transparent, unless the application has just upgraded to ABCI 2.0. +to switch are met [RFC-100](../../docs/references/rfc/rfc-100-abci-vote-extension-propag.md#base-implementation-persist-and-propagate-extended-commit-history). +From the application's point of view, these operations are transparent, unless the application has just upgraded to ABCI 2.0. In that case, the application needs to be properly configured and aware of certain constraints in terms of when -to provide vote extensions. More details can be found in the section below. +to provide vote extensions. More details can be found in the section below. Once a node switches to consensus, it operates like any other node, apart from having a truncated block history at the height of the restored snapshot. @@ -1111,12 +1111,12 @@ Once a node switches to consensus, it operates like any other node, apart from h Introducing vote extensions requires changes to the configuration of the application. -First of all, switching to a version of CometBFT with vote extensions, requires a coordinated upgrade. -For a detailed description on the upgrade path, please refer to the corresponding -[section](./../../docs/rfc/rfc-100-abci-vote-extension-propag.md#upgrade-path) in RFC-100. +First of all, switching to a version of CometBFT with vote extensions, requires a coordinated upgrade. +For a detailed description on the upgrade path, please refer to the corresponding +[section](../../docs/references/rfc/rfc-100-abci-vote-extension-propag.md#upgrade-path) in RFC-100. -There is a newly introduced [**consensus parameter**](./abci%2B%2B_app_requirements.md#abciparamsvoteextensionsenableheight): `VoteExtensionsEnableHeight`. -This parameter represents the height at which vote extensions are +There is a newly introduced [**consensus parameter**](./abci%2B%2B_app_requirements.md#abciparamsvoteextensionsenableheight): `VoteExtensionsEnableHeight`. +This parameter represents the height at which vote extensions are required for consensus to proceed, with 0 being the default value (no vote extensions). A chain can enable vote extensions either: * at genesis by setting `VoteExtensionsEnableHeight` to be equal, e.g., to the `InitialHeight` @@ -1125,7 +1125,7 @@ A chain can enable vote extensions either: Once the (coordinated) upgrade to ABCI 2.0 has taken place, at height *hu*, the value of `VoteExtensionsEnableHeight` MAY be set to some height, *he*, -which MUST be higher than the current height of the chain. Thus the earliest value for +which MUST be higher than the current height of the chain. Thus the earliest value for *he* is *hu* + 1. Once a node reaches the configured height, @@ -1137,7 +1137,7 @@ Likewise, for all heights *h < he*, any precommit messages that *do* will also be rejected as malformed. Height *he* is somewhat special, as calls to `PrepareProposal` MUST NOT have vote extension data, but all precommit votes in that height MUST carry a vote extension, -even if the extension is `nil`. +even if the extension is `nil`. Height *he + 1* is the first height for which `PrepareProposal` MUST have vote extension data and all precommit votes in that height MUST have a vote extension. diff --git a/spec/abci/abci++_comet_expected_behavior.md b/spec/abci/abci++_comet_expected_behavior.md index 3af4278035d..2c8026d2988 100644 --- a/spec/abci/abci++_comet_expected_behavior.md +++ b/spec/abci/abci++_comet_expected_behavior.md @@ -105,15 +105,15 @@ Let us now examine the grammar line by line, providing further details. >start = clean-start / recovery >``` -* If the process is starting from scratch, depending on whether the _state-sync_ is enabled, it engages in the handshake -with the Application, or it starts the _state-sync_ mechanism to catch up with other processes. Finally, it enters +* If the process is starting from scratch, depending on whether the _state-sync_ is enabled, it engages in the handshake +with the Application, or it starts the _state-sync_ mechanism to catch up with other processes. Finally, it enters normal consensus execution. >```abnf >clean-start = ( app-handshake / state-sync ) consensus-exec >``` -* If _state-sync_ is disabled, CometBFT calls `Info` method and then +* If _state-sync_ is disabled, CometBFT calls `Info` method and then since the process is starting from scratch and the Application has no state CometBFT calls `InitChain`. >```abnf @@ -126,10 +126,10 @@ since the process is starting from scratch and the Application has no state Come to provide the Application with all the snapshots needed, in order to reconstruct the state locally. A successful attempt must provide at least one chunk via `ApplySnapshotChunk`. At the end of a successful attempt, CometBFT calls `Info` to make sure the reconstructed state's - _AppHash_ matches the one in the block header at the corresponding height. Note that the state - of the application does not contain vote extensions itself. The application can rely on - [CometBFT to ensure](./../../docs/rfc/rfc-100-abci-vote-extension-propag.md#base-implementation-persist-and-propagate-extended-commit-history) - the node has all the relevant data to proceed with the execution beyond this point. + _AppHash_ matches the one in the block header at the corresponding height. Note that the state + of the application does not contain vote extensions itself. The application can rely on + [CometBFT to ensure](../../docs/references/rfc/rfc-100-abci-vote-extension-propag.md#base-implementation-persist-and-propagate-extended-commit-history) + the node has all the relevant data to proceed with the execution beyond this point. >```abnf >state-sync = *state-sync-attempt success-sync info @@ -137,7 +137,7 @@ since the process is starting from scratch and the Application has no state Come >success-sync = offer-snapshot 1*apply-chunk >``` -* In recovery mode, CometBFT first calls `Info` to know from which height it needs to replay decisions to the Application. If the Application +* In recovery mode, CometBFT first calls `Info` to know from which height it needs to replay decisions to the Application. If the Application did not store any state CometBFT calls `InitChain`. After this, CometBFT enters consensus execution, first in replay mode, if there are blocks to replay, and then in normal mode. >```abnf @@ -172,7 +172,7 @@ did not store any state CometBFT calls `InitChain`. After this, CometBFT enters Following a crash between (i) and (ii) and in (the likely) case `PrepareProposal` produces a different block, the signing of this block will fail, which means that the new block will not be stored or broadcast. If the crash happened after (ii), then signing fails but nothing happens to the stored block. - + If a block was stored, it is sent to all validators, including the proposer. Receiving a proposal block triggers `ProcessProposal` with such a block. @@ -247,21 +247,21 @@ needed to move the return of `AppHash` to `FinalizeBlock`. ## Accommodating for vote extensions In a manner transparent to the application, CometBFT ensures the node is provided with all -the data it needs to participate in consensus. +the data it needs to participate in consensus. In the case of recovering from a crash, or joining the network via state sync, CometBFT will make -sure the node acquires the necessary vote extensions before switching to consensus. +sure the node acquires the necessary vote extensions before switching to consensus. -If a node is already in consensus but falls behind, during catch-up, CometBFT will provide the node with +If a node is already in consensus but falls behind, during catch-up, CometBFT will provide the node with vote extensions from past heights by retrieving the extensions within `ExtendedCommit` for old heights that it had previously stored. -We realize this is sub-optimal due to the increase in storage needed to store the extensions, we are +We realize this is sub-optimal due to the increase in storage needed to store the extensions, we are working on an optimization of this implementation which should alleviate this concern. However, the application can use the existing `retain_height` parameter to decide how much history it wants to keep, just as is done with the block history. The network-wide implications of the usage of `retain_height` stay the same. -The decision to store -historical commits and potential optimizations, are discussed in detail in [RFC-100](./../../docs/rfc/rfc-100-abci-vote-extension-propag.md#current-limitations-and-possible-implementations) +The decision to store +historical commits and potential optimizations, are discussed in detail in [RFC-100](../../docs/references/rfc/rfc-100-abci-vote-extension-propag.md#current-limitations-and-possible-implementations) ## Handling upgrades to ABCI 2.0 From baa6c55005e685064d44b51f7b0e5aed54862c75 Mon Sep 17 00:00:00 2001 From: Andy Nogueira Date: Mon, 22 Jan 2024 16:26:46 -0500 Subject: [PATCH 3/7] re-creating explanation section (#1613) --- docs/README.md | 4 +-- docs/app-dev/app-architecture.md | 2 +- docs/app-dev/getting-started.md | 6 ++-- docs/core/README.md | 23 --------------- docs/data-companion/README.md | 12 -------- docs/explanation/README.md | 28 +++++++++++++++++++ docs/explanation/core/README.md | 23 +++++++++++++++ .../{ => explanation}/core/block-structure.md | 0 docs/{ => explanation}/core/block-sync.md | 0 docs/{ => explanation}/core/configuration.md | 2 +- .../core/how-to-read-logs.md | 6 ++-- docs/{ => explanation}/core/light-client.md | 0 docs/{ => explanation}/core/mempool.md | 4 +-- docs/{ => explanation}/core/metrics.md | 0 docs/{ => explanation}/core/rpc.md | 0 .../core/running-in-production.md | 16 +++++------ docs/{ => explanation}/core/state-sync.md | 0 docs/{ => explanation}/core/subscription.md | 26 ++++++++--------- docs/{ => explanation}/core/using-cometbft.md | 6 ++-- docs/{ => explanation}/core/validators.md | 6 ++-- docs/explanation/data-companion/README.md | 12 ++++++++ docs/{ => explanation}/data-companion/grpc.md | 2 +- .../{ => explanation}/data-companion/intro.md | 2 +- .../data-companion/pruning.md | 0 docs/{ => explanation}/introduction/README.md | 4 +-- docs/networks/docker-compose.md | 2 +- docs/tutorials/quick-start.md | 2 +- spec/abci/abci++_app_requirements.md | 2 +- 28 files changed, 109 insertions(+), 81 deletions(-) delete mode 100644 docs/core/README.md delete mode 100644 docs/data-companion/README.md create mode 100644 docs/explanation/README.md create mode 100644 docs/explanation/core/README.md rename docs/{ => explanation}/core/block-structure.md (100%) rename docs/{ => explanation}/core/block-sync.md (100%) rename docs/{ => explanation}/core/configuration.md (99%) rename docs/{ => explanation}/core/how-to-read-logs.md (98%) rename docs/{ => explanation}/core/light-client.md (100%) rename docs/{ => explanation}/core/mempool.md (97%) rename docs/{ => explanation}/core/metrics.md (100%) rename docs/{ => explanation}/core/rpc.md (100%) rename docs/{ => explanation}/core/running-in-production.md (96%) rename docs/{ => explanation}/core/state-sync.md (100%) rename docs/{ => explanation}/core/subscription.md (87%) rename docs/{ => explanation}/core/using-cometbft.md (99%) rename docs/{ => explanation}/core/validators.md (97%) create mode 100644 docs/explanation/data-companion/README.md rename docs/{ => explanation}/data-companion/grpc.md (99%) rename docs/{ => explanation}/data-companion/intro.md (90%) rename docs/{ => explanation}/data-companion/pruning.md (100%) rename docs/{ => explanation}/introduction/README.md (99%) diff --git a/docs/README.md b/docs/README.md index c13ca2f4ca7..be49e5af5de 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,14 +16,14 @@ CometBFT serves blockchain applications. More formally, CometBFT performs Byzantine Fault Tolerant (BFT) State Machine Replication (SMR) for arbitrary deterministic, finite state machines. -For more background, see [What is CometBFT?](introduction/README.md#what-is-cometbft.md). +For more background, see [What is CometBFT?](explanation/introduction/README.md#what-is-cometbft.md). To get started quickly with an example application, see the [quick start guide](guides/quick-start.md). To learn about application development on CometBFT, see the [Application Blockchain Interface](https://github.com/cometbft/cometbft/tree/main/spec/abci). For more details on using CometBFT, see the respective documentation for -[CometBFT internals](core/), [benchmarking and monitoring](tools/), and [network deployments](networks/). +[CometBFT internals](explanation/core/), [benchmarking and monitoring](tools/), and [network deployments](networks/). ## Contribute diff --git a/docs/app-dev/app-architecture.md b/docs/app-dev/app-architecture.md index fe22582faba..6d78769164c 100644 --- a/docs/app-dev/app-architecture.md +++ b/docs/app-dev/app-architecture.md @@ -51,5 +51,5 @@ See the following for more extensive documentation: - [Interchain Standard for the Light-Client REST API](https://github.com/cosmos/cosmos-sdk/pull/1617) (legacy/deprecated) - [CometBFT RPC Docs](https://docs.cometbft.com/main/rpc/) -- [CometBFT in Production](../core/running-in-production.md) +- [CometBFT in Production](../explanation/core/running-in-production.md) - [ABCI spec](https://github.com/cometbft/cometbft/tree/main/spec/abci) diff --git a/docs/app-dev/getting-started.md b/docs/app-dev/getting-started.md index f2ce5221cf8..1f509d98d86 100644 --- a/docs/app-dev/getting-started.md +++ b/docs/app-dev/getting-started.md @@ -11,7 +11,7 @@ application you want to run. So, to run a complete blockchain that does something useful, you must start two programs: one is CometBFT, the other is your application, which can be written in any programming language. Recall from [the intro to -ABCI](../introduction/what-is-cometbft.md#abci-overview) that CometBFT +ABCI](../explanation/introduction/what-is-cometbft.md#abci-overview) that CometBFT handles all the p2p and consensus stuff, and just forwards transactions to the application when they need to be validated, or when they're ready to be executed and committed. @@ -92,7 +92,7 @@ abci-cli kvstore In another terminal, we can start CometBFT. You should already have the CometBFT binary installed. If not, follow the steps from -[here](../introduction/install.md). If you have never run CometBFT +[here](../explanation/introduction/install.md). If you have never run CometBFT before, use: ```sh @@ -103,7 +103,7 @@ cometbft node If you have used CometBFT, you may want to reset the data for a new blockchain by running `cometbft unsafe-reset-all`. Then you can run `cometbft node` to start CometBFT, and connect to the app. For more -details, see [the guide on using CometBFT](../core/using-cometbft.md). +details, see [the guide on using CometBFT](../explanation/core/using-cometbft.md). You should see CometBFT making blocks! We can get the status of our CometBFT node as follows: diff --git a/docs/core/README.md b/docs/core/README.md deleted file mode 100644 index 26cb7a40607..00000000000 --- a/docs/core/README.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -order: 1 -parent: - title: Core - order: 4 ---- - -# Overview - -This section dives into the internals of the CometBFT's implementation. - -- [Using CometBFT](./using-cometbft.md) -- [Configuration](./configuration.md) -- [Running in Production](./running-in-production.md) -- [Metrics](./metrics.md) -- [Validators](./validators.md) -- [Subscribing to events](./subscription.md) -- [Block Structure](./block-structure.md) -- [RPC](./rpc.md) -- [Block Sync](./block-sync.md) -- [State Sync](./state-sync.md) -- [Mempool](./mempool.md) -- [Light Client](./light-client.md) diff --git a/docs/data-companion/README.md b/docs/data-companion/README.md deleted file mode 100644 index 4bc2b579fc5..00000000000 --- a/docs/data-companion/README.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -order: false -parent: - title: Data Companion - order: 6 ---- - -# Guides - -- [Introduction](./intro.md) -- [gRPC services](./grpc.md) -- [Pruning service](./pruning.md) diff --git a/docs/explanation/README.md b/docs/explanation/README.md new file mode 100644 index 00000000000..f53f40eb516 --- /dev/null +++ b/docs/explanation/README.md @@ -0,0 +1,28 @@ +--- +order: 3 +title: CometBFT Explained +description: Explanation +parent: + order: 1 +--- + +# CometBFT Explained + +## The comprehensive guide to understanding CometBFT + +This section is designed to provide you with a comprehensive understanding of the core +concepts that underpin CometBFT. You will delve into the block structure, explore the +light client, gain insights into mempool, and learn about state sync, among other essential +concepts. + +This section also includes information about the new Data Companion gRPC endpoints +that allow external applications to access data from the node and manage data pruning. +This allows storage optimization and node performance by keeping only necessary data. + +By the end of this section, you will have a firm grasp of the fundamental +principles that make CometBFT a powerful technology in the realm of distributed systems. + +- [Introduction](./introduction/README.md) +- [Core Concepts](./core/README.md) +- [Data Companion](./data-companion/README.md) +- diff --git a/docs/explanation/core/README.md b/docs/explanation/core/README.md new file mode 100644 index 00000000000..2512adc18be --- /dev/null +++ b/docs/explanation/core/README.md @@ -0,0 +1,23 @@ +--- +order: 1 +parent: + title: Core + order: 4 +--- + +# Overview + +This section dives into the internals of the CometBFT's implementation. + +- [Using CometBFT](using-cometbft.md) +- [Configuration](configuration.md) +- [Running in Production](running-in-production.md) +- [Metrics](metrics.md) +- [Validators](validators.md) +- [Subscribing to events](subscription.md) +- [Block Structure](block-structure.md) +- [RPC](rpc.md) +- [Block Sync](block-sync.md) +- [State Sync](state-sync.md) +- [Mempool](mempool.md) +- [Light Client](light-client.md) diff --git a/docs/core/block-structure.md b/docs/explanation/core/block-structure.md similarity index 100% rename from docs/core/block-structure.md rename to docs/explanation/core/block-structure.md diff --git a/docs/core/block-sync.md b/docs/explanation/core/block-sync.md similarity index 100% rename from docs/core/block-sync.md rename to docs/explanation/core/block-sync.md diff --git a/docs/core/configuration.md b/docs/explanation/core/configuration.md similarity index 99% rename from docs/core/configuration.md rename to docs/explanation/core/configuration.md index 25874937cf8..bc8c79164b5 100644 --- a/docs/core/configuration.md +++ b/docs/explanation/core/configuration.md @@ -564,7 +564,7 @@ CometBFT will only create blocks if there are transactions, or after waiting ## Consensus timeouts explained There's a variety of information about timeouts in [Running in -production](./running-in-production.md#configuration-parameters). +production](running-in-production.md#configuration-parameters). You can also find more detailed explanation in the paper describing the Tendermint consensus algorithm, adopted by CometBFT: [The latest diff --git a/docs/core/how-to-read-logs.md b/docs/explanation/core/how-to-read-logs.md similarity index 98% rename from docs/core/how-to-read-logs.md rename to docs/explanation/core/how-to-read-logs.md index de3eb7dfe99..6f2db00285b 100644 --- a/docs/core/how-to-read-logs.md +++ b/docs/explanation/core/how-to-read-logs.md @@ -111,7 +111,7 @@ I[10-04|13:54:30.410] Recheck txs module=mempoo Here is the list of modules you may encounter in CometBFT's log and a little overview what they do. -- `abci-client` As mentioned in [Application Development Guide](../app-dev/abci-cli.md), CometBFT acts as an ABCI +- `abci-client` As mentioned in [Application Development Guide](../../app-dev/abci-cli.md), CometBFT acts as an ABCI client with respect to the application and maintains 3 connections: mempool, consensus and query. The code used by CometBFT can be found [here](https://github.com/cometbft/cometbft/blob/main/abci/client). @@ -126,13 +126,13 @@ little overview what they do. found [here](https://github.com/cometbft/cometbft/blob/main/types/events.go). You can subscribe to them by calling `subscribe` RPC method. Refer - to [RPC docs](./rpc.md) for additional information. + to [RPC docs](rpc.md) for additional information. - `mempool` Mempool module handles all incoming transactions, whenever they are coming from peers or the application. - `p2p` Provides an abstraction around peer-to-peer communication. For more details, please check out the [README](https://github.com/cometbft/cometbft/blob/main/p2p/README.md). -- `rpc` [CometBFT's RPC](./rpc.md). +- `rpc` [CometBFT's RPC](rpc.md). - `rpc-server` RPC server. For implementation details, please read the [doc.go](https://github.com/cometbft/cometbft/blob/main/rpc/jsonrpc/doc.go). - `state` Represents the latest state and execution submodule, which diff --git a/docs/core/light-client.md b/docs/explanation/core/light-client.md similarity index 100% rename from docs/core/light-client.md rename to docs/explanation/core/light-client.md diff --git a/docs/core/mempool.md b/docs/explanation/core/mempool.md similarity index 97% rename from docs/core/mempool.md rename to docs/explanation/core/mempool.md index f86083ee04d..f38668ca18c 100644 --- a/docs/core/mempool.md +++ b/docs/explanation/core/mempool.md @@ -99,5 +99,5 @@ The ABCI application becomes responsible for storing, disseminating, and proposing transactions using [`PrepareProposal`][2]. The concrete design is up to the ABCI application developers. -[1]: ../../spec/abci/abci++_methods.md#checktx -[2]: ../../spec/abci/abci++_methods.md#prepareproposal \ No newline at end of file +[1]: ../../../spec/abci/abci++_methods.md#checktx +[2]: ../../../spec/abci/abci++_methods.md#prepareproposal diff --git a/docs/core/metrics.md b/docs/explanation/core/metrics.md similarity index 100% rename from docs/core/metrics.md rename to docs/explanation/core/metrics.md diff --git a/docs/core/rpc.md b/docs/explanation/core/rpc.md similarity index 100% rename from docs/core/rpc.md rename to docs/explanation/core/rpc.md diff --git a/docs/core/running-in-production.md b/docs/explanation/core/running-in-production.md similarity index 96% rename from docs/core/running-in-production.md rename to docs/explanation/core/running-in-production.md index 7dd374b4af9..f610dd031c4 100644 --- a/docs/core/running-in-production.md +++ b/docs/explanation/core/running-in-production.md @@ -24,13 +24,13 @@ CometBFT keeps multiple distinct databases in the `$CMTHOME/data`: - `tx_index.db`: Indexes txs (and their results) by tx hash and by DeliverTx result events. By default, CometBFT will only index txs by their hash and height, not by their DeliverTx -result events. See [indexing transactions](../app-dev/indexing-transactions.md) for +result events. See [indexing transactions](../../app-dev/indexing-transactions.md) for details. Applications can expose block pruning strategies to the node operator. Please read the documentation of your application to find out more details. -Applications can use [state sync](./state-sync.md) to help nodes bootstrap quickly. +Applications can use [state sync](state-sync.md) to help nodes bootstrap quickly. ## Logging @@ -38,7 +38,7 @@ Default logging level (`log_level = "main:info,state:info,statesync:info,*:error normal operation mode. Read [this post](https://blog.cosmos.network/one-of-the-exciting-new-features-in-0-10-0-release-is-smart-log-level-flag-e2506b4ab756) for details on how to configure `log_level` config variable. Some of the -modules can be found [here](./how-to-read-logs.md#list-of-modules). If +modules can be found [here](how-to-read-logs.md#list-of-modules). If you're trying to debug CometBFT or asked to provide logs with debug logging level, you can do so by running CometBFT with `--log_level="*:debug"`. @@ -76,7 +76,7 @@ For the above reasons, the `mempool.wal` is disabled by default. To enable, set ## DoS Exposure and Mitigation -Validators are supposed to setup [Sentry Node Architecture](./validators.md) +Validators are supposed to setup [Sentry Node Architecture](validators.md) to prevent Denial-of-Service attacks. ### P2P @@ -129,7 +129,7 @@ for more information. ## Debugging CometBFT If you ever have to debug CometBFT, the first thing you should probably do is -check out the logs. See [How to read logs](./how-to-read-logs.md), where we +check out the logs. See [How to read logs](how-to-read-logs.md), where we explain what certain log statements mean. If, after skimming through the logs, things are not clear still, the next thing @@ -154,7 +154,7 @@ just the votes seen at the current height. If, after consulting with the logs and above endpoints, you still have no idea what's happening, consider using `cometbft debug kill` sub-command. This command will scrap all the available info and kill the process. See -[Debugging](../tools/debugging.md) for the exact format. +[Debugging](../../tools/debugging.md) for the exact format. You can inspect the resulting archive yourself or create an issue on [Github](https://github.com/cometbft/cometbft). Before opening an issue @@ -171,10 +171,10 @@ Other useful endpoints include mentioned earlier `/status`, `/net_info` and `/validators`. CometBFT also can report and serve Prometheus metrics. See -[Metrics](./metrics.md). +[Metrics](metrics.md). `cometbft debug dump` sub-command can be used to periodically dump useful -information into an archive. See [Debugging](../tools/debugging.md) for more +information into an archive. See [Debugging](../../tools/debugging.md) for more information. ## What happens when my app dies diff --git a/docs/core/state-sync.md b/docs/explanation/core/state-sync.md similarity index 100% rename from docs/core/state-sync.md rename to docs/explanation/core/state-sync.md diff --git a/docs/core/subscription.md b/docs/explanation/core/subscription.md similarity index 87% rename from docs/core/subscription.md rename to docs/explanation/core/subscription.md index b6be5f3b36f..5892a7f6359 100644 --- a/docs/core/subscription.md +++ b/docs/explanation/core/subscription.md @@ -38,26 +38,26 @@ more information on query syntax and other options. You can also use tags, given you had included them into DeliverTx response, to query transaction results. See [Indexing -transactions](../app-dev/indexing-transactions.md) for details. +transactions](../../app-dev/indexing-transactions.md) for details. ## Query parameter and event type restrictions -While CometBFT imposes no restrictions on the application with regards to the type of -the event output, there are several considerations that need to be taken into account +While CometBFT imposes no restrictions on the application with regards to the type of +the event output, there are several considerations that need to be taken into account when querying events with numeric values. - Queries convert all numeric event values to `big.Float` , provided by `math/big`. Integers are converted into a float with a precision equal to the number of bits needed -to represent this integer. This is done to avoid precision loss for big integers when they -are converted with the default precision (`64`). -- When comparing two values, if either one of them is a float, the other one will be represented -as a big float. Integers are again parsed as big floats with a precision equal to the number -of bits required to represent them. -- As with all floating point comparisons, comparing floats with decimal values can lead to imprecise -results. -- Queries cannot include negative numbers - -Prior to version `v0.38.x`, floats were not supported as query parameters. +to represent this integer. This is done to avoid precision loss for big integers when they +are converted with the default precision (`64`). +- When comparing two values, if either one of them is a float, the other one will be represented +as a big float. Integers are again parsed as big floats with a precision equal to the number +of bits required to represent them. +- As with all floating point comparisons, comparing floats with decimal values can lead to imprecise +results. +- Queries cannot include negative numbers + +Prior to version `v0.38.x`, floats were not supported as query parameters. ## ValidatorSetUpdates diff --git a/docs/core/using-cometbft.md b/docs/explanation/core/using-cometbft.md similarity index 99% rename from docs/core/using-cometbft.md rename to docs/explanation/core/using-cometbft.md index 82ec9a30422..1708f1e3fc9 100644 --- a/docs/core/using-cometbft.md +++ b/docs/explanation/core/using-cometbft.md @@ -248,7 +248,7 @@ address book files. ## Configuration CometBFT uses a `config.toml` for configuration. For details, see [the -config specification](./configuration.md). +config specification](configuration.md). Notable options include the socket address of the application (`proxy_app`), the listening address of the CometBFT peer @@ -338,7 +338,7 @@ Note the mempool does not provide strong guarantees - just because a tx passed CheckTx (ie. was accepted into the mempool), doesn't mean it will be committed, as nodes with the tx in their mempool may crash before they get to propose. For more information, see the [mempool -write-ahead-log](./running-in-production.md#mempool-wal) +write-ahead-log](running-in-production.md#mempool-wal) ## CometBFT Networks @@ -552,7 +552,7 @@ failing, you need at least four validator nodes (e.g., 2/3). Updating validators in a live network is supported but must be explicitly programmed by the application developer. See the [application -developers guide](../app-dev/abci-cli.md) for more details. +developers guide](../../app-dev/abci-cli.md) for more details. ### Local Network diff --git a/docs/core/validators.md b/docs/explanation/core/validators.md similarity index 97% rename from docs/core/validators.md rename to docs/explanation/core/validators.md index 86c4626ee6c..631600367b5 100644 --- a/docs/core/validators.md +++ b/docs/explanation/core/validators.md @@ -25,7 +25,7 @@ Validators have a cryptographic key-pair and an associated amount of There are two ways to become validator. -1. They can be pre-established in the [genesis state](./using-cometbft.md#genesis) +1. They can be pre-established in the [genesis state](using-cometbft.md#genesis) 2. The ABCI app responds to the FinalizeBlock message with changes to the existing validator set. @@ -35,7 +35,7 @@ When setting up a validator there are countless ways to configure your setup. Th ### Network Layout -![ALT Network Layout](../imgs/sentry_layout.png) +![ALT Network Layout](../../imgs/sentry_layout.png) The diagram is based on AWS, other cloud providers will have similar solutions to design a solution. Running nodes is not limited to cloud providers, you can run nodes on bare metal systems as well. The architecture will be the same no matter which setup you decide to go with. @@ -49,7 +49,7 @@ A more persistent solution (not detailed on the diagram) is to have multiple dir ### Local Configuration -![ALT Local Configuration](../imgs/sentry_local_config.png) +![ALT Local Configuration](../../imgs/sentry_local_config.png) The validator will only talk to the sentry that are provided, the sentry nodes will communicate to the validator via a secret connection and the rest of the network through a normal connection. The sentry nodes do have the option of communicating with each other as well. diff --git a/docs/explanation/data-companion/README.md b/docs/explanation/data-companion/README.md new file mode 100644 index 00000000000..32f97388942 --- /dev/null +++ b/docs/explanation/data-companion/README.md @@ -0,0 +1,12 @@ +--- +order: false +parent: + title: Data Companion + order: 6 +--- + +# Guides + +- [Introduction](intro.md) +- [gRPC services](grpc.md) +- [Pruning service](pruning.md) diff --git a/docs/data-companion/grpc.md b/docs/explanation/data-companion/grpc.md similarity index 99% rename from docs/data-companion/grpc.md rename to docs/explanation/data-companion/grpc.md index 42bdca29859..b34d0d3ae4a 100644 --- a/docs/data-companion/grpc.md +++ b/docs/explanation/data-companion/grpc.md @@ -213,4 +213,4 @@ to effectively influence the pruning of blocks and state, ABCI results (if enabl indexer data on the node. For a comprehensive understanding of the pruning service, please see the document -[Pruning service](./pruning.md). +[Pruning service](pruning.md). diff --git a/docs/data-companion/intro.md b/docs/explanation/data-companion/intro.md similarity index 90% rename from docs/data-companion/intro.md rename to docs/explanation/data-companion/intro.md index c8144542630..eba44b7b303 100644 --- a/docs/data-companion/intro.md +++ b/docs/explanation/data-companion/intro.md @@ -22,5 +22,5 @@ indexer data and transaction indexer data. By also using the new gRPC services, it's possible now to retrieve data from the node, such as `block` and `block results` in a more efficient way. -The [gRPC services](./grpc.md) document provides practical information and insights that will guide you through the +The [gRPC services](grpc.md) document provides practical information and insights that will guide you through the process of using these services in order to create a Data Companion service. diff --git a/docs/data-companion/pruning.md b/docs/explanation/data-companion/pruning.md similarity index 100% rename from docs/data-companion/pruning.md rename to docs/explanation/data-companion/pruning.md diff --git a/docs/introduction/README.md b/docs/explanation/introduction/README.md similarity index 99% rename from docs/introduction/README.md rename to docs/explanation/introduction/README.md index 7eae0c1ecc7..a5f11207619 100644 --- a/docs/introduction/README.md +++ b/docs/explanation/introduction/README.md @@ -230,7 +230,7 @@ design their message handlers to create a blockchain that does anything useful but this architecture provides a place to start. The diagram below illustrates the flow of messages via ABCI. -![abci](../imgs/abci.png) +![abci](../../imgs/abci.png) ## A Note on Determinism @@ -265,7 +265,7 @@ CometBFT adopts [Tendermint consensus][tendermint-paper], an easy-to-understand, mostly asynchronous, BFT consensus algorithm. The algorithm follows a simple state machine that looks like this: -![consensus-logic](../imgs/consensus_logic.png) +![consensus-logic](../../imgs/consensus_logic.png) Participants in the algorithm are called **validators**; they take turns proposing blocks of transactions and voting on them. Blocks are diff --git a/docs/networks/docker-compose.md b/docs/networks/docker-compose.md index d2edce42d58..9e49657c5f8 100644 --- a/docs/networks/docker-compose.md +++ b/docs/networks/docker-compose.md @@ -8,7 +8,7 @@ With Docker Compose, you can spin up local testnets with a single command. ## Requirements -1. [Install CometBFT](../introduction/install.md) +1. [Install CometBFT](../explanation/introduction/install.md) 2. [Install docker](https://docs.docker.com/engine/installation/) 3. [Install docker-compose](https://docs.docker.com/compose/install/) diff --git a/docs/tutorials/quick-start.md b/docs/tutorials/quick-start.md index 4f21165adc8..f2f0131f3fe 100644 --- a/docs/tutorials/quick-start.md +++ b/docs/tutorials/quick-start.md @@ -159,6 +159,6 @@ cometbft node --home ./mytestnet/node3 --proxy_app=kvstore --p2p.persistent_peer Note that after the third node is started, blocks will start to stream in because >2/3 of validators (defined in the `genesis.json`) have come online. -Persistent peers can also be specified in the `config.toml`. See [here](../core/configuration.md) for more information about configuration options. +Persistent peers can also be specified in the `config.toml`. See [here](../explanation/core/configuration.md) for more information about configuration options. Transactions can then be sent as covered in the single, local node example above. diff --git a/spec/abci/abci++_app_requirements.md b/spec/abci/abci++_app_requirements.md index 34f632f3976..23415eda960 100644 --- a/spec/abci/abci++_app_requirements.md +++ b/spec/abci/abci++_app_requirements.md @@ -603,7 +603,7 @@ the header, the validator set, and any included evidence in the block. The Application should be aware that honest validators _may_ produce and broadcast blocks with up to the configured `MaxBytes` size. As a result, the consensus -[timeout parameters](../../docs/core/configuration.md#consensus-timeouts-explained) +[timeout parameters](../../docs/explanation/core/configuration.md#consensus-timeouts-explained) adopted by nodes should be configured so as to account for the worst-case latency for the delivery of a full block with `MaxBytes` size to all validators. From c28963e3a99d4ca92d4f3793932eda2f23d2cf18 Mon Sep 17 00:00:00 2001 From: Andy Nogueira Date: Mon, 22 Jan 2024 16:57:31 -0500 Subject: [PATCH 4/7] re-structuring for the how-to guides section (#1613) --- abci/README.md | 2 +- docs/README.md | 2 +- docs/app-dev/README.md | 12 --------- docs/explanation/README.md | 2 +- docs/explanation/core/how-to-read-logs.md | 2 +- .../explanation/core/running-in-production.md | 6 ++--- docs/explanation/core/subscription.md | 2 +- docs/explanation/core/using-cometbft.md | 2 +- docs/guides/README.md | 25 +++++++++++++++++++ docs/guides/app-dev/README.md | 12 +++++++++ docs/{ => guides}/app-dev/abci-cli.md | 2 +- docs/{ => guides}/app-dev/app-architecture.md | 2 +- docs/{ => guides}/app-dev/getting-started.md | 2 +- .../app-dev/indexing-transactions.md | 0 docs/{ => guides}/networks/README.md | 2 +- docs/{ => guides}/networks/docker-compose.md | 2 +- docs/{ => guides}/tools/README.md | 2 +- docs/{ => guides}/tools/debugging.md | 0 docs/tutorials/README.md | 2 +- 19 files changed, 53 insertions(+), 28 deletions(-) delete mode 100644 docs/app-dev/README.md create mode 100644 docs/guides/README.md create mode 100644 docs/guides/app-dev/README.md rename docs/{ => guides}/app-dev/abci-cli.md (99%) rename docs/{ => guides}/app-dev/app-architecture.md (97%) rename docs/{ => guides}/app-dev/getting-started.md (98%) rename docs/{ => guides}/app-dev/indexing-transactions.md (100%) rename docs/{ => guides}/networks/README.md (67%) rename docs/{ => guides}/networks/docker-compose.md (98%) rename docs/{ => guides}/tools/README.md (91%) rename docs/{ => guides}/tools/debugging.md (100%) diff --git a/abci/README.md b/abci/README.md index 787af29e3bd..fdbe05ac579 100644 --- a/abci/README.md +++ b/abci/README.md @@ -12,7 +12,7 @@ Previously, the ABCI was referred to as TMSP. ## Installation & Usage -To get up and running quickly, see the [getting started guide](../docs/app-dev/getting-started.md) along with the [abci-cli documentation](../docs/app-dev/abci-cli.md) which will go through the examples found in the [examples](./example/) directory. +To get up and running quickly, see the [getting started guide](../docs/guides/app-dev/getting-started.md) along with the [abci-cli documentation](../docs/guides/app-dev/abci-cli.md) which will go through the examples found in the [examples](./example/) directory. ## Specification diff --git a/docs/README.md b/docs/README.md index be49e5af5de..293d253de30 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,7 +23,7 @@ To get started quickly with an example application, see the [quick start guide]( To learn about application development on CometBFT, see the [Application Blockchain Interface](https://github.com/cometbft/cometbft/tree/main/spec/abci). For more details on using CometBFT, see the respective documentation for -[CometBFT internals](explanation/core/), [benchmarking and monitoring](tools/), and [network deployments](networks/). +[CometBFT internals](explanation/core/), [benchmarking and monitoring](guides/tools/), and [network deployments](networks/). ## Contribute diff --git a/docs/app-dev/README.md b/docs/app-dev/README.md deleted file mode 100644 index aff0a570ca2..00000000000 --- a/docs/app-dev/README.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -order: false -parent: - order: 3 ---- - -# Apps - -- [Using ABCI-CLI](./abci-cli.md) -- [Getting Started](./getting-started.md) -- [Indexing transactions](./indexing-transactions.md) -- [Application Architecture Guide](./app-architecture.md) diff --git a/docs/explanation/README.md b/docs/explanation/README.md index f53f40eb516..9118c7c0bf4 100644 --- a/docs/explanation/README.md +++ b/docs/explanation/README.md @@ -1,5 +1,5 @@ --- -order: 3 +order: 1 title: CometBFT Explained description: Explanation parent: diff --git a/docs/explanation/core/how-to-read-logs.md b/docs/explanation/core/how-to-read-logs.md index 6f2db00285b..f42fe49c9bc 100644 --- a/docs/explanation/core/how-to-read-logs.md +++ b/docs/explanation/core/how-to-read-logs.md @@ -111,7 +111,7 @@ I[10-04|13:54:30.410] Recheck txs module=mempoo Here is the list of modules you may encounter in CometBFT's log and a little overview what they do. -- `abci-client` As mentioned in [Application Development Guide](../../app-dev/abci-cli.md), CometBFT acts as an ABCI +- `abci-client` As mentioned in [Application Development Guide](../../guides/app-dev/abci-cli.md), CometBFT acts as an ABCI client with respect to the application and maintains 3 connections: mempool, consensus and query. The code used by CometBFT can be found [here](https://github.com/cometbft/cometbft/blob/main/abci/client). diff --git a/docs/explanation/core/running-in-production.md b/docs/explanation/core/running-in-production.md index f610dd031c4..8d95ca156c4 100644 --- a/docs/explanation/core/running-in-production.md +++ b/docs/explanation/core/running-in-production.md @@ -24,7 +24,7 @@ CometBFT keeps multiple distinct databases in the `$CMTHOME/data`: - `tx_index.db`: Indexes txs (and their results) by tx hash and by DeliverTx result events. By default, CometBFT will only index txs by their hash and height, not by their DeliverTx -result events. See [indexing transactions](../../app-dev/indexing-transactions.md) for +result events. See [indexing transactions](../../guides/app-dev/indexing-transactions.md) for details. Applications can expose block pruning strategies to the node operator. @@ -154,7 +154,7 @@ just the votes seen at the current height. If, after consulting with the logs and above endpoints, you still have no idea what's happening, consider using `cometbft debug kill` sub-command. This command will scrap all the available info and kill the process. See -[Debugging](../../tools/debugging.md) for the exact format. +[Debugging](../../guides/tools/debugging.md) for the exact format. You can inspect the resulting archive yourself or create an issue on [Github](https://github.com/cometbft/cometbft). Before opening an issue @@ -174,7 +174,7 @@ CometBFT also can report and serve Prometheus metrics. See [Metrics](metrics.md). `cometbft debug dump` sub-command can be used to periodically dump useful -information into an archive. See [Debugging](../../tools/debugging.md) for more +information into an archive. See [Debugging](../../guides/tools/debugging.md) for more information. ## What happens when my app dies diff --git a/docs/explanation/core/subscription.md b/docs/explanation/core/subscription.md index 5892a7f6359..99f01f8522e 100644 --- a/docs/explanation/core/subscription.md +++ b/docs/explanation/core/subscription.md @@ -38,7 +38,7 @@ more information on query syntax and other options. You can also use tags, given you had included them into DeliverTx response, to query transaction results. See [Indexing -transactions](../../app-dev/indexing-transactions.md) for details. +transactions](../../guides/app-dev/indexing-transactions.md) for details. ## Query parameter and event type restrictions diff --git a/docs/explanation/core/using-cometbft.md b/docs/explanation/core/using-cometbft.md index 1708f1e3fc9..06df62ddef5 100644 --- a/docs/explanation/core/using-cometbft.md +++ b/docs/explanation/core/using-cometbft.md @@ -552,7 +552,7 @@ failing, you need at least four validator nodes (e.g., 2/3). Updating validators in a live network is supported but must be explicitly programmed by the application developer. See the [application -developers guide](../../app-dev/abci-cli.md) for more details. +developers guide](../../guides/app-dev/abci-cli.md) for more details. ### Local Network diff --git a/docs/guides/README.md b/docs/guides/README.md new file mode 100644 index 00000000000..1e7e674f67c --- /dev/null +++ b/docs/guides/README.md @@ -0,0 +1,25 @@ +--- +order: 2 +title: CometBFT How-to Guides +description: How-to Guides +parent: + order: 1 +--- + +# CometBFT How-To Guides + +CometBFT How-To Guides is a resource center that provides users with comprehensive guides +on how to develop applications, use essential tools, and run networks powered by the +CometBFT consensus algorithm. The guides are suitable for developers, system administrators, +and blockchain enthusiasts who want to gain practical skills and knowledge in distributed +systems and blockchain technology using CometBFT. + +The CometBFT How-To Guides are designed to provide step-by-step instructions and practical +examples to help users acquire real-world experience while learning. + +The primary objective of CometBFT How-To Guides is to equip users with the necessary +skills and knowledge to become experts in CometBFT. + +- [Application Development](./app-dev/README.md) +- [Tools](./tools/README.md) +- [Running Networks](./networks/README.md) diff --git a/docs/guides/app-dev/README.md b/docs/guides/app-dev/README.md new file mode 100644 index 00000000000..abde0fc08bc --- /dev/null +++ b/docs/guides/app-dev/README.md @@ -0,0 +1,12 @@ +--- +order: false +parent: + order: 3 +--- + +# Apps + +- [Using ABCI-CLI](abci-cli.md) +- [Getting Started](getting-started.md) +- [Indexing transactions](indexing-transactions.md) +- [Application Architecture Guide](app-architecture.md) diff --git a/docs/app-dev/abci-cli.md b/docs/guides/app-dev/abci-cli.md similarity index 99% rename from docs/app-dev/abci-cli.md rename to docs/guides/app-dev/abci-cli.md index 6b45ace7377..c38da3372e7 100644 --- a/docs/app-dev/abci-cli.md +++ b/docs/guides/app-dev/abci-cli.md @@ -203,7 +203,7 @@ connects to the app using four separate connections, each with its own pattern of messages. For examples of running an ABCI app with CometBFT, see the -[getting started guide](./getting-started.md). +[getting started guide](getting-started.md). ## Bounties diff --git a/docs/app-dev/app-architecture.md b/docs/guides/app-dev/app-architecture.md similarity index 97% rename from docs/app-dev/app-architecture.md rename to docs/guides/app-dev/app-architecture.md index 6d78769164c..a8b4fd41603 100644 --- a/docs/app-dev/app-architecture.md +++ b/docs/guides/app-dev/app-architecture.md @@ -51,5 +51,5 @@ See the following for more extensive documentation: - [Interchain Standard for the Light-Client REST API](https://github.com/cosmos/cosmos-sdk/pull/1617) (legacy/deprecated) - [CometBFT RPC Docs](https://docs.cometbft.com/main/rpc/) -- [CometBFT in Production](../explanation/core/running-in-production.md) +- [CometBFT in Production](../../explanation/core/running-in-production.md) - [ABCI spec](https://github.com/cometbft/cometbft/tree/main/spec/abci) diff --git a/docs/app-dev/getting-started.md b/docs/guides/app-dev/getting-started.md similarity index 98% rename from docs/app-dev/getting-started.md rename to docs/guides/app-dev/getting-started.md index 1f509d98d86..d576f5b52a0 100644 --- a/docs/app-dev/getting-started.md +++ b/docs/guides/app-dev/getting-started.md @@ -103,7 +103,7 @@ cometbft node If you have used CometBFT, you may want to reset the data for a new blockchain by running `cometbft unsafe-reset-all`. Then you can run `cometbft node` to start CometBFT, and connect to the app. For more -details, see [the guide on using CometBFT](../explanation/core/using-cometbft.md). +details, see [the guide on using CometBFT](../../explanation/core/using-cometbft.md). You should see CometBFT making blocks! We can get the status of our CometBFT node as follows: diff --git a/docs/app-dev/indexing-transactions.md b/docs/guides/app-dev/indexing-transactions.md similarity index 100% rename from docs/app-dev/indexing-transactions.md rename to docs/guides/app-dev/indexing-transactions.md diff --git a/docs/networks/README.md b/docs/guides/networks/README.md similarity index 67% rename from docs/networks/README.md rename to docs/guides/networks/README.md index ceea235985d..caeb3a682ba 100644 --- a/docs/networks/README.md +++ b/docs/guides/networks/README.md @@ -7,7 +7,7 @@ parent: # Overview -Use [Docker Compose](./docker-compose.md) to spin up CometBFT testnets on your +Use [Docker Compose](docker-compose.md) to spin up CometBFT testnets on your local machine. See the `cometbft testnet --help` command for more help initializing testnets. diff --git a/docs/networks/docker-compose.md b/docs/guides/networks/docker-compose.md similarity index 98% rename from docs/networks/docker-compose.md rename to docs/guides/networks/docker-compose.md index 9e49657c5f8..32c027cb4c6 100644 --- a/docs/networks/docker-compose.md +++ b/docs/guides/networks/docker-compose.md @@ -59,7 +59,7 @@ calling the `cometbft testnet` command. The `./build` directory is mounted to the `/cometbft` mount point to attach the binary and config files to the container. -To change the number of validators / non-validators change the `localnet-start` Makefile target [here](../../Makefile): +To change the number of validators / non-validators change the `localnet-start` Makefile target [here](../../../Makefile): ```makefile localnet-start: localnet-stop diff --git a/docs/tools/README.md b/docs/guides/tools/README.md similarity index 91% rename from docs/tools/README.md rename to docs/guides/tools/README.md index 22d31486bf5..068b927ffa5 100644 --- a/docs/tools/README.md +++ b/docs/guides/tools/README.md @@ -9,7 +9,7 @@ parent: CometBFT has some tools that are associated with it for: -- [Debugging](./debugging.md) +- [Debugging](debugging.md) - [Benchmarking](#benchmarking) ## Benchmarking diff --git a/docs/tools/debugging.md b/docs/guides/tools/debugging.md similarity index 100% rename from docs/tools/debugging.md rename to docs/guides/tools/debugging.md diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index 1de81698b51..dba34b36b24 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -1,5 +1,5 @@ --- -order: 1 +order: 3 title: Tutorials description: Tutorials parent: From ded4539b70ad6148cb0f73e9190805ce8398c9e3 Mon Sep 17 00:00:00 2001 From: Andy Nogueira Date: Tue, 23 Jan 2024 15:21:51 -0500 Subject: [PATCH 5/7] changes to landing docs (#1613) --- docs/explanation/README.md | 1 - docs/guides/README.md | 5 +---- docs/references/README.md | 7 ++----- docs/tutorials/README.md | 4 ++-- 4 files changed, 5 insertions(+), 12 deletions(-) diff --git a/docs/explanation/README.md b/docs/explanation/README.md index 9118c7c0bf4..905a72eeff9 100644 --- a/docs/explanation/README.md +++ b/docs/explanation/README.md @@ -25,4 +25,3 @@ principles that make CometBFT a powerful technology in the realm of distributed - [Introduction](./introduction/README.md) - [Core Concepts](./core/README.md) - [Data Companion](./data-companion/README.md) -- diff --git a/docs/guides/README.md b/docs/guides/README.md index 1e7e674f67c..16a37f131ed 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -6,7 +6,7 @@ parent: order: 1 --- -# CometBFT How-To Guides +# How-To Guides CometBFT How-To Guides is a resource center that provides users with comprehensive guides on how to develop applications, use essential tools, and run networks powered by the @@ -17,9 +17,6 @@ systems and blockchain technology using CometBFT. The CometBFT How-To Guides are designed to provide step-by-step instructions and practical examples to help users acquire real-world experience while learning. -The primary objective of CometBFT How-To Guides is to equip users with the necessary -skills and knowledge to become experts in CometBFT. - - [Application Development](./app-dev/README.md) - [Tools](./tools/README.md) - [Running Networks](./networks/README.md) diff --git a/docs/references/README.md b/docs/references/README.md index ca49f829476..68fbfdcd6ec 100644 --- a/docs/references/README.md +++ b/docs/references/README.md @@ -1,12 +1,12 @@ --- order: 4 -title: Reference Documentation +title: CometBFT Reference Documentation description: References parent: order: 1 --- -# CometBFT Reference Documentation +# Reference Documentation Welcome to the CometBFT Reference Documentation, a comprehensive resource for essential information and standards related to CometBFT. @@ -39,9 +39,6 @@ to ensure that CometBFT meets and exceeds industry benchmarks. - Testing methodologies and strategies. - Documentation on test plans and test cases. -- Guidelines for test automation. -- Processes for defect tracking and resolution. -- Continuous improvement practices. Explore the QA documents to understand the testing methods to ensure the quality and performance of CometBFT. diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index dba34b36b24..70d1f0e154f 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -1,12 +1,12 @@ --- order: 3 -title: Tutorials +title: CometBFT Tutorials description: Tutorials parent: order: 1 --- -# Welcome to CometBFT Tutorials +## Tutorials Are you ready to explore the world of CometBFT, the cutting-edge consensus algorithm that's revolutionizing the field of distributed systems? You've come to the right place! Our CometBFT Tutorials provide the knowledge From a98645c23918ef964f325197ff7b59a96d01eb5b Mon Sep 17 00:00:00 2001 From: Andy Nogueira Date: Wed, 24 Jan 2024 16:13:42 -0500 Subject: [PATCH 6/7] fixing broken links (#1613) --- docs/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index 293d253de30..0f6a45c3227 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,14 +16,14 @@ CometBFT serves blockchain applications. More formally, CometBFT performs Byzantine Fault Tolerant (BFT) State Machine Replication (SMR) for arbitrary deterministic, finite state machines. -For more background, see [What is CometBFT?](explanation/introduction/README.md#what-is-cometbft.md). +For more background, see [What is CometBFT?](explanation/introduction/README.md). -To get started quickly with an example application, see the [quick start guide](guides/quick-start.md). +To get started quickly with an example application, see the [quick start guide](tutorials/quick-start.md). To learn about application development on CometBFT, see the [Application Blockchain Interface](https://github.com/cometbft/cometbft/tree/main/spec/abci). For more details on using CometBFT, see the respective documentation for -[CometBFT internals](explanation/core/), [benchmarking and monitoring](guides/tools/), and [network deployments](networks/). +[CometBFT internals](explanation/core/), [benchmarking and monitoring](guides/tools/), and [network deployments](guides/networks/). ## Contribute From b8ac224357361e21e13eec4eedce68a59017a560 Mon Sep 17 00:00:00 2001 From: Andy Nogueira Date: Wed, 24 Jan 2024 17:19:29 -0500 Subject: [PATCH 7/7] fixing additional broken links (#1613) --- docs/README.md | 2 +- docs/explanation/core/configuration.md | 2 +- docs/guides/networks/docker-compose.md | 2 +- docs/references/rfc/README.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/README.md b/docs/README.md index 0f6a45c3227..1560a757464 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,7 +16,7 @@ CometBFT serves blockchain applications. More formally, CometBFT performs Byzantine Fault Tolerant (BFT) State Machine Replication (SMR) for arbitrary deterministic, finite state machines. -For more background, see [What is CometBFT?](explanation/introduction/README.md). +For more background, see [What is CometBFT?](./explanation/introduction/README.md). To get started quickly with an example application, see the [quick start guide](tutorials/quick-start.md). diff --git a/docs/explanation/core/configuration.md b/docs/explanation/core/configuration.md index bc8c79164b5..25874937cf8 100644 --- a/docs/explanation/core/configuration.md +++ b/docs/explanation/core/configuration.md @@ -564,7 +564,7 @@ CometBFT will only create blocks if there are transactions, or after waiting ## Consensus timeouts explained There's a variety of information about timeouts in [Running in -production](running-in-production.md#configuration-parameters). +production](./running-in-production.md#configuration-parameters). You can also find more detailed explanation in the paper describing the Tendermint consensus algorithm, adopted by CometBFT: [The latest diff --git a/docs/guides/networks/docker-compose.md b/docs/guides/networks/docker-compose.md index 32c027cb4c6..8a1cdea5487 100644 --- a/docs/guides/networks/docker-compose.md +++ b/docs/guides/networks/docker-compose.md @@ -8,7 +8,7 @@ With Docker Compose, you can spin up local testnets with a single command. ## Requirements -1. [Install CometBFT](../explanation/introduction/install.md) +1. [Install CometBFT](../../tutorials/install.md) 2. [Install docker](https://docs.docker.com/engine/installation/) 3. [Install docker-compose](https://docs.docker.com/compose/install/) diff --git a/docs/references/rfc/README.md b/docs/references/rfc/README.md index a12c0ffe4e9..f4bb42feabb 100644 --- a/docs/references/rfc/README.md +++ b/docs/references/rfc/README.md @@ -15,7 +15,7 @@ discussion that might otherwise only be recorded in an ad-hoc way (for example, via gists or Google docs) that are difficult to discover for someone after the fact. An RFC _may_ give rise to more specific architectural _decisions_ for CometBFT, but those decisions must be recorded separately in -[Architecture Decision Records (ADR)](../references/architecture/). +[Architecture Decision Records (ADR)](./../architecture/README.md). As a rule of thumb, if you can articulate a specific question that needs to be answered, write an ADR. If you need to explore the topic and get input from