forked from cometbft/cometbft
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
d8ffae5
commit ab137d9
Showing
19 changed files
with
1,892 additions
and
187 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| diff --git a/.github/auto_request_review.yml b/.github/auto_request_review.yml | ||
| new file mode 100644 | ||
| index 000000000..32ab61b10 | ||
| --- /dev/null | ||
| +++ b/.github/auto_request_review.yml | ||
| @@ -0,0 +1,14 @@ | ||
| +# More info at https://github.com/necojackarc/auto-request-review | ||
| +reviewers: | ||
| + defaults: | ||
| + - cmwaters | ||
| + - evan-forbes | ||
| + - ninabarbakadze | ||
| + - rach-id | ||
| + - rootulp | ||
| + | ||
| +options: | ||
| + ignore_draft: true | ||
| + ignored_keywords: | ||
| + - DO NOT REVIEW | ||
| + enable_group_assignment: false |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,208 +1,85 @@ | ||
| # CometBFT | ||
| # celestia-core | ||
|
|
||
| [Byzantine-Fault Tolerant][bft] [State Machine Replication][smr]. Or | ||
| [Blockchain], for short. | ||
| [](https://pkg.go.dev/github.com/celestiaorg/celestia-core) | ||
| [](https://github.com/celestiaorg/celestia-core/releases/latest) | ||
| [](https://goreportcard.com/report/github.com/celestiaorg/celestia-core) | ||
| [](https://github.com/celestiaorg/celestia-core/actions/workflows/lint.yml) | ||
| [](https://github.com/celestiaorg/celestia-core/actions/workflows/tests.yml) | ||
|
|
||
| [![Version][version-badge]][version-url] | ||
| [![API Reference][api-badge]][api-url] | ||
| [![Go version][go-badge]][go-url] | ||
| [![Discord chat][discord-badge]][discord-url] | ||
| [![License][license-badge]][license-url] | ||
| [![Sourcegraph][sg-badge]][sg-url] | ||
| celestia-core is a fork of [cometbft/cometbft](https://github.com/cometbft/cometbft), an implementation of the Tendermint protocol, with the following changes: | ||
| <!-- TODO: change links when new repo is setup --> | ||
| 1. Modifications to how `DataHash` in the block header is determined. In CometBFT, `DataHash` is based on the transactions included in a block. In Celestia, block data (including transactions) are erasure coded into a data square to enable data availability sampling. In order for the header to contain a commitment to this data square, `DataHash` was modified to be the Merkle root of the row and column roots of the erasure coded data square. See [ADR 008](https://github.com/celestiaorg/celestia-core/blob/v0.34.x-celestia/docs/celestia-architecture/adr-008-updating-to-tendermint-v0.35.x.md?plain=1#L20) for the motivation or [celestia-app/pkg/da/data_availability_header.go](https://github.com/celestiaorg/celestia-app/blob/2f89956b22c4c3cfdec19b3b8601095af6f69804/pkg/da/data_availability_header.go) for the implementation. Note on the implementation: celestia-app computes the hash in prepare_proposal and returns it to CometBFT via [`blockData.Hash`](https://github.com/celestiaorg/celestia-app/blob/5bbdac2d3f46662a34b2111602b8f964d6e6fba5/app/prepare_proposal.go#L78) so a modification to celestia-core isn't strictly necessary but [comments](https://github.com/celestiaorg/celestia-core/blob/2ec23f804691afc196d0104616e6c880d4c1ca41/types/block.go#L1041-L1042) were added. | ||
|
|
||
| | Branch | Tests | Linting | | ||
| |---------|------------------------------------------------|---------------------------------------------| | ||
| | main | [![Tests][tests-badge]][tests-url] | [![Lint][lint-badge]][lint-url] | | ||
| | v1.x | [![Tests][tests-badge-v1x]][tests-url-v1x] | [![Lint][lint-badge-v1x]][lint-url-v1x] | | ||
| | v0.38.x | [![Tests][tests-badge-v038x]][tests-url-v038x] | [![Lint][lint-badge-v038x]][lint-url-v038x] | | ||
| | v0.37.x | [![Tests][tests-badge-v037x]][tests-url-v037x] | [![Lint][lint-badge-v037x]][lint-url-v037x] | | ||
| | v0.34.x | [![Tests][tests-badge-v034x]][tests-url-v034x] | [![Lint][lint-badge-v034x]][lint-url-v034x] | | ||
|
|
||
| CometBFT is a Byzantine Fault Tolerant (BFT) middleware that takes a | ||
| state transition machine - written in any programming language - and securely | ||
| replicates it on many machines. | ||
| See [./docs/celestia-architecture](./docs/celestia-architecture/) for architecture decision records (ADRs) on Celestia modifications. | ||
|
|
||
| It is a fork of [Tendermint Core][tm-core] and implements the Tendermint | ||
| consensus algorithm. | ||
| ## Diagram | ||
|
|
||
| For protocol details, refer to the [CometBFT Specification](./spec/README.md). | ||
| ```ascii | ||
| ^ +-------------------------------+ ^ | ||
| | | | | | ||
| | | State-machine = Application | | | ||
| | | | | celestia-app (built with Cosmos SDK) | ||
| | | ^ + | | | ||
| | +----------- | ABCI | ----------+ v | ||
| Celestia | | + v | ^ | ||
| validator or | | | | | ||
| full consensus | | Consensus | | | ||
| node | | | | | ||
| | +-------------------------------+ | celestia-core (fork of CometBFT) | ||
| | | | | | ||
| | | Networking | | | ||
| | | | | | ||
| v +-------------------------------+ v | ||
| ``` | ||
|
|
||
| For detailed analysis of the consensus protocol, including safety and liveness | ||
| proofs, read our paper, "[The latest gossip on BFT | ||
| consensus](https://arxiv.org/abs/1807.04938)". | ||
| ## Install | ||
|
|
||
| ## Documentation | ||
| See <https://github.com/celestiaorg/celestia-app#install> | ||
|
|
||
| Complete documentation can be found on the | ||
| [website](https://docs.cometbft.com/). | ||
| ## Usage | ||
|
|
||
| ## Releases | ||
| See <https://github.com/celestiaorg/celestia-app#usage> | ||
|
|
||
| Please do not depend on `main` as your production branch, as it may receive | ||
| significant breaking changes at any time. Use | ||
| [releases](https://github.com/cometbft/cometbft/releases) instead. | ||
|
|
||
| If you intend to run CometBFT in production, we're happy to help. To contact us, | ||
| in order of preference: | ||
|
|
||
| - [Create a new discussion on | ||
| GitHub](https://github.com/cometbft/cometbft/discussions) | ||
| - Reach out to us via [Telegram](https://t.me/CometBFT) | ||
| - [Join the Cosmos Network Discord](https://discord.gg/interchain) and | ||
| discuss in | ||
| [`#cometbft`](https://discord.com/channels/669268347736686612/1069933855307472906) | ||
|
|
||
| More on how releases are conducted can be found [here](./RELEASES.md). | ||
|
|
||
| ## Security | ||
| ## Contributing | ||
|
|
||
| Please see [SECURITY.md](./SECURITY.md). | ||
| This repo intends on preserving the minimal possible diff with [cometbft/cometbft](https://github.com/cometbft/cometbft) to make fetching upstream changes easy. If the proposed contribution is | ||
|
|
||
| ## Minimum requirements | ||
| - **specific to Celestia**: consider if [celestia-app](https://github.com/celestiaorg/celestia-app) is a better target | ||
| - **not specific to Celestia**: consider making the contribution upstream in CometBFT | ||
|
|
||
| | CometBFT version | Requirement | Version | Tested with | | ||
| |------------------|-------------|----------------|--------------| | ||
| | main | Go version | 1.23 or higher | up to 1.23.5 | | ||
| | v1.x | Go version | 1.23 or higher | up to 1.23.1 | | ||
| | v0.38.x | Go version | 1.22 or higher | up to 1.22 | | ||
| | v0.37.x | Go version | 1.22 or higher | up to 1.22 | | ||
| | v0.34.x | Go version | 1.22 or higher | up to 1.22 | | ||
| 1. [Install Go](https://go.dev/doc/install) 1.23.5+ | ||
| 2. Fork this repo | ||
| 3. Clone your fork | ||
| 4. Find an issue to work on (see [good first issues](https://github.com/celestiaorg/celestia-core/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)) | ||
| 5. Work on a change in a branch on your fork | ||
| 6. When your change is ready, push your branch and create a PR that targets this repo | ||
|
|
||
| ### Install | ||
| ### Helpful Commands | ||
|
|
||
| See the [install guide](docs/tutorials/install.md). | ||
| ```sh | ||
| # Build a new CometBFT binary and output to build/comet | ||
| make build | ||
|
|
||
| ### Quick Start | ||
| # Install CometBFT binary | ||
| make install | ||
|
|
||
| - [Single node](docs/tutorials/quick-start.md) | ||
| - [Local cluster using docker-compose](./docs/guides/networks/docker-compose.md) | ||
| # Run tests | ||
| make test | ||
|
|
||
| ## Contributing | ||
| # If you modified any protobuf definitions in a `*.proto` file then | ||
| # you may need to lint, format, and generate updated `*.pb.go` files | ||
| make proto-lint | ||
| make proto-format | ||
| make proto-gen | ||
| ``` | ||
|
|
||
| Please abide by the [Code of Conduct](CODE_OF_CONDUCT.md) in all interactions. | ||
| ## Branches | ||
|
|
||
| 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/references/architecture/README.md) and [Request For Comments | ||
| (RFCs)](docs/references/rfc/README.md). | ||
| The canonical branches in this repo are based on CometBFT releases. For example: [`v1.x-celestia`](https://github.com/celestiaorg/celestia-core/tree/v1.x-celestia) is based on the CometBFT `v1.x` release branch and contains Celestia-specific changes. | ||
|
|
||
| ## Versioning | ||
|
|
||
| As of v1, CometBFT uses the following approach to versioning: | ||
|
|
||
| - **Major version** bumps, such as v1.0.0 to v2.0.0, would generally involve | ||
| changes that _force_ users to perform a coordinated upgrade in order to use | ||
| the new version, such as protocol-breaking changes (e.g. changes to how block | ||
| hashes are computed and thus what the network considers to be "valid blocks", | ||
| or how the consensus protocol works, or changes that affect network-level | ||
| compatibility between nodes, etc.). | ||
| - **Minor version** bumps, such as v1.1.0 to v1.2.0, are reserved for rolling | ||
| out new features or substantial changes that do not force a coordinated | ||
| upgrade (i.e. not protocol-breaking), but could potentially break Go APIs. | ||
| - **Patch version** bumps, such as v1.0.0 to v1.0.1, are reserved for | ||
| bug/security fixes that are not protocol- or Go API-breaking. | ||
|
|
||
| ### Upgrades | ||
|
|
||
| We do not guarantee compatibility between major releases of CometBFT. Minor | ||
| releases of the same major release series (v1.1, v1.2, etc.) should, unless | ||
| otherwise specified, be compatible with each other. Patch releases of the same | ||
| minor release series (v1.0.1, v1.0.2, etc.) are guaranteed to be compatible with | ||
| each other. | ||
|
|
||
| For more detailed information on upgrading from one version to another, see | ||
| [UPGRADING.md](./UPGRADING.md). | ||
|
|
||
| ### Supported Versions | ||
|
|
||
| Because we are a small core team, we have limited capacity to ship patch | ||
| updates, including security updates. Consequently, we strongly recommend keeping | ||
| CometBFT up-to-date. Upgrading instructions can be found in | ||
| [UPGRADING.md](./UPGRADING.md). | ||
|
|
||
| Currently supported versions include: | ||
|
|
||
| - v1.x: Currently in pre-release with no guarantees as to API stability until a | ||
| release candidate is cut. See [RELEASES.md](./RELEASES.md) for details on our | ||
| process as to API stability guarantees that can be expected of CometBFT | ||
| pre-releases. | ||
| - v0.38.x: CometBFT v0.38 introduces ABCI 2.0, which implements the entirety of | ||
| ABCI++ | ||
| - v0.37.x: CometBFT v0.37 introduces ABCI 1.0, which is the first major step | ||
| towards the full ABCI++ implementation in ABCI 2.0 | ||
| - v0.34.x: The CometBFT v0.34 series is compatible with the Tendermint Core | ||
| v0.34 series | ||
|
|
||
| ## Resources | ||
|
|
||
| ### Libraries | ||
|
|
||
| - [Cosmos SDK](http://github.com/cosmos/cosmos-sdk): A framework for building | ||
| high-value public blockchain applications in Go | ||
| - [Tendermint in Rust](https://github.com/informalsystems/tendermint-rs) | ||
| - [ABCI Tower](https://github.com/penumbra-zone/tower-abci) | ||
|
|
||
| ### Applications | ||
|
|
||
| - [Cosmos Hub](https://hub.cosmos.network/) | ||
| - [Celestia](https://celestia.org/) | ||
| - [Anoma](https://anoma.network/) | ||
| - [Vocdoni](https://developer.vocdoni.io/) | ||
|
|
||
| ### Research | ||
|
|
||
| Below are links to the original Tendermint consensus algorithm and relevant | ||
| whitepapers, which CometBFT will continue to build on. | ||
|
|
||
| - [The latest gossip on BFT consensus](https://arxiv.org/abs/1807.04938) | ||
| - [Master's Thesis on Tendermint](https://atrium.lib.uoguelph.ca/xmlui/handle/10214/9769) | ||
| - [Original Whitepaper: "Tendermint: Consensus Without Mining"](https://tendermint.com/static/docs/tendermint.pdf) | ||
|
|
||
| ## Join us | ||
|
|
||
| CometBFT is currently maintained by [Informal | ||
| Systems](https://informal.systems). If you'd like to work full-time on CometBFT, | ||
| [we're hiring](https://informal.systems/careers)! | ||
|
|
||
| Funding for CometBFT development comes primarily from the [Interchain | ||
| Foundation](https://interchain.io), a Swiss non-profit. Informal Systems also | ||
| maintains [cometbft.com](https://cometbft.com). | ||
|
|
||
| [bft]: https://en.wikipedia.org/wiki/Byzantine_fault_tolerance | ||
| [smr]: https://en.wikipedia.org/wiki/State_machine_replication | ||
| [Blockchain]: https://en.wikipedia.org/wiki/Blockchain | ||
| [version-badge]: https://img.shields.io/github/v/release/cometbft/cometbft.svg | ||
| [version-url]: https://github.com/cometbft/cometbft/releases/latest | ||
| [api-badge]: https://camo.githubusercontent.com/915b7be44ada53c290eb157634330494ebe3e30a/68747470733a2f2f676f646f632e6f72672f6769746875622e636f6d2f676f6c616e672f6764646f3f7374617475732e737667 | ||
| [api-url]: https://pkg.go.dev/github.com/cometbft/cometbft | ||
| [go-badge]: https://img.shields.io/badge/go-1.21-blue.svg | ||
| [go-url]: https://github.com/moovweb/gvm | ||
| [discord-badge]: https://img.shields.io/discord/669268347736686612.svg | ||
| [discord-url]: https://discord.gg/interchain | ||
| [license-badge]: https://img.shields.io/github/license/cometbft/cometbft.svg | ||
| [license-url]: https://github.com/cometbft/cometbft/blob/main/LICENSE | ||
| [sg-badge]: https://sourcegraph.com/github.com/cometbft/cometbft/-/badge.svg | ||
| [sg-url]: https://sourcegraph.com/github.com/cometbft/cometbft?badge | ||
| [tests-url]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml | ||
| [tests-url-v1x]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml?query=branch%3Av1.x | ||
| [tests-url-v038x]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml?query=branch%3Av0.38.x | ||
| [tests-url-v037x]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml?query=branch%3Av0.37.x | ||
| [tests-url-v034x]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml?query=branch%3Av0.34.x | ||
| [tests-badge]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml/badge.svg?branch=main | ||
| [tests-badge-v1x]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml/badge.svg?branch=v1.x | ||
| [tests-badge-v038x]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml/badge.svg?branch=v0.38.x | ||
| [tests-badge-v037x]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml/badge.svg?branch=v0.37.x | ||
| [tests-badge-v034x]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml/badge.svg?branch=v0.34.x | ||
| [lint-badge]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml/badge.svg?branch=main | ||
| [lint-badge-v034x]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml/badge.svg?branch=v0.34.x | ||
| [lint-badge-v037x]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml/badge.svg?branch=v0.37.x | ||
| [lint-badge-v038x]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml/badge.svg?branch=v0.38.x | ||
| [lint-badge-v1x]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml/badge.svg?branch=v1.x | ||
| [lint-url]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml | ||
| [lint-url-v034x]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml?query=branch%3Av0.34.x | ||
| [lint-url-v037x]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml?query=branch%3Av0.37.x | ||
| [lint-url-v038x]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml?query=branch%3Av0.38.x | ||
| [lint-url-v1x]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml?query=branch%3Av1.x | ||
| [tm-core]: https://github.com/tendermint/tendermint | ||
| Releases are formatted: `v<CELESTIA_CORE_VERSION>-tm-v<COMETBFT_CORE_VERSION>` | ||
| For example: [`v1.4.0-tm-v0.34.20`](https://github.com/celestiaorg/celestia-core/releases/tag/v1.4.0-tm-v0.34.20) is celestia-core version `1.4.0` based on CometBFT `0.34.20`. | ||
| `CELESTIA_CORE_VERSION` strives to adhere to [Semantic Versioning](http://semver.org/). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| --- | ||
| order: 1 | ||
| parent: | ||
| order: false | ||
| --- | ||
|
|
||
| # Tendermint and Celestia | ||
|
|
||
| celestia-core is not meant to be used as a general purpose framework. | ||
| Instead, its main purpose is to provide certain components (mainly consensus but also a p2p layer for Tx gossiping) for the Celestia main chain. | ||
| Hence, we do not provide any extensive documentation here. | ||
|
|
||
| Instead of keeping a copy of the Tendermint documentation, we refer to the existing extensive and maintained documentation and specification: | ||
|
|
||
| - <https://docs.tendermint.com/> | ||
| - <https://github.com/tendermint/tendermint/tree/master/docs/> | ||
| - <https://github.com/tendermint/spec> | ||
|
|
||
| Reading these will give you a lot of background and context on Tendermint which will also help you understand how celestia-core and [celestia-app](https://github.com/celestiaorg/celestia-app) interact with each other. | ||
|
|
||
| ## Celestia | ||
|
|
||
| As mentioned above, celestia-core aims to be more focused on the Celestia use-case than vanilla Tendermint. | ||
| Moving forward we might provide a clear overview on the changes we incorporated. | ||
| For now, we refer to the Celestia specific ADRs in this repository as well as to the Celestia specification: | ||
|
|
||
| - [celestia-specs](https://github.com/celestiaorg/celestia-specs) | ||
|
|
||
| ## Architecture Decision Records (ADR) | ||
|
|
||
| This is a location to record all high-level architecture decisions in this repository. | ||
|
|
||
| You can read more about the ADR concept in this [blog post](https://product.reverb.com/documenting-architecture-decisions-the-reverb-way-a3563bb24bd0#.78xhdix6t). | ||
|
|
||
| An ADR should provide: | ||
|
|
||
| - Context on the relevant goals and the current state | ||
| - Proposed changes to achieve the goals | ||
| - Summary of pros and cons | ||
| - References | ||
| - Changelog | ||
|
|
||
| Note the distinction between an ADR and a spec. The ADR provides the context, intuition, reasoning, and | ||
| justification for a change in architecture, or for the architecture of something | ||
| new. The spec is much more compressed and streamlined summary of everything as | ||
| it stands today. | ||
|
|
||
| If recorded decisions turned out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match. | ||
|
|
||
| Note the context/background should be written in the present tense. | ||
|
|
||
| To start a new ADR, you can use this template: [adr-template.md](./adr-template.md) | ||
|
|
||
| ### Table of Contents | ||
|
|
||
| - [ADR 001: Erasure Coding Block Propagation](./adr-001-block-propagation.md) | ||
| - [ADR 002: Sampling erasure coded Block chunks](./adr-002-ipld-da-sampling.md) | ||
| - [ADR 003: Retrieving Application messages](./adr-003-application-data-retrieval.md) | ||
| - [ADR 004: Data Availability Sampling Light Client](./adr-004-mvp-light-client.md) | ||
| - [ADR 005: Decouple BlockID and PartSetHeader](./adr-005-decouple-blockid-and-partsetheader.md) | ||
| - [ADR 006: Row Propagation](./adr-006-row-propagation.md) | ||
| - [ADR 007: Minimal Changes to Tendermint](./adr-007-minimal-changes-to-tendermint.md) | ||
| - [ADR 008: Updating to Tendermint v0.35.x](./adr-008-updating-to-tendermint-v0.35.x.md) |
Oops, something went wrong.