cometbft · andynog · Jan 25, 2024 · Jan 19, 2024 · Jan 19, 2024 · Jan 22, 2024
@@ -20,24 +20,24 @@ 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.
    The massive surface area of previous versions has in the past significantly
    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,15 +132,15 @@ 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.*`
   and introduced versioned packages to distinguish between proto definitions
   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)

@@ -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

@@ -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
@@ -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
 

@@ -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:
 

@@ -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
 

@@ -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).
 
-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](core/), [benchmarking and monitoring](tools/), and [network deployments](networks/).
+[CometBFT internals](explanation/core/), [benchmarking and monitoring](guides/tools/), and [network deployments](guides/networks/).
 
 ## Contribute
 

@@ -0,0 +1,27 @@
+---
+order: 1
+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)