celestia-core
celestia-core is a fork of cometbft/cometbft, an implementation of the Tendermint protocol, with the following changes:
- Early adoption of the ABCI++ methods:
PrepareProposal and ProcessProposal because they haven't yet landed in a CometBFT release.
- 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 for the motivation or celestia-app/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 so a modification to celestia-core isn't strictly necessary but comments were added.
- The GRPC server exposed by CometBFT was modified to expose Celestia-specific APIs:
- A propagation reactor was added to support Celestia's block propagation needs. It gossips compact blocks, tracks which proposal parts peers have or want, and helps recover missing proposal parts during consensus.
See ./docs/celestia-architecture for architecture decision records (ADRs) on Celestia modifications.
Diagram
^ +-------------------------------+ ^
| | | |
| | 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
Install
See https://github.com/celestiaorg/celestia-app#install
Usage
See https://github.com/celestiaorg/celestia-app#usage
Contributing
This repo intends on preserving the minimal possible diff with cometbft/cometbft to make fetching upstream changes easy. If the proposed contribution is
- specific to Celestia: consider if celestia-app is a better target
- not specific to Celestia: consider making the contribution upstream in CometBFT
- Install Go 1.23.6+
- Fork this repo
- Clone your fork
- Find an issue to work on (see good first issues)
- Work on a change in a branch on your fork
- When your change is ready, push your branch and create a PR that targets this repo
PR titles follow conventional commits and must start the subject with [high], [medium], or [low] to indicate the review thoroughness needed. For example: fix(mempool)!: [high] reject oversized txs or docs: [low] clarify setup instructions. Don't repeat the tag in the PR description; the title already carries it.
[high]: Deep review for consensus, state transitions, security, or other changes with significant risk. Examples: consensus, mempool/CAT, p2p, ABCI, state and block execution, light client, crypto, and breaking changes.[medium]: Standard review for code changes with limited impact and well-understood behavior.[low]: Focused review for straightforward docs, tests, or tooling changes with low risk.
Choose the higher level when unsure. A small diff can still need deep review. CI checks the title format; reviewers should confirm the chosen level. Dependabot uses [high] for Go module updates and [medium] for GitHub Actions updates. Mergify backport PRs reuse the original PR's title, so they keep its tag.
Helpful Commands
# Build a new CometBFT binary and output to build/comet
make build
# Install CometBFT binary
make install
# Run tests
make test
# 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
Branches
main is the canonical branch for development. Most PRs should target main and optionally be backported to a release branch.
main is the development line for the next celestia-app major version. The next v0.X.x release branch is cut from main for it, so main will become v0.43.x for celestia-app v11.x. Changes intended only for an upcoming celestia-app version, such as behavior gated on a new app version, belong on main. Release branches only take backports of fixes that also apply to the celestia-app versions they serve.
| Branch | Based on CometBFT | Release format | Used by celestia-app |
|---|
main | v0.38.x | v0.43.0 (unreleased) | v11.x (main) |
v0.42.x | v0.38.x | v0.42.0 | v10.x |
v0.40.x | v0.38.x | v0.40.0 | v9.x |
v0.39.x-celestia | v0.38.x | v0.39.0 | v6.x through v8.x |
v0.38.x-celestia | v0.38.x | v1.54.1-tm-v0.38.17 | v4.x and v5.x |
v0.34.x-celestia | v0.34.x | v1.52.1-tm-v0.34.35 | v1.x through v3.x |
Branches cut from main after v0.39.x-celestia have no -celestia suffix. Newer celestia-app versions still depend on v0.34.x-celestia to multiplex ABCI v1 requests, via a github.com/tendermint/tendermint replace directive.
Until the next release branch is cut, celestia-app main may temporarily pin a release from the previous branch (for example a v0.42.x release).
The replace directives in celestia-app's go.mod are the source of truth for which celestia-core version a given celestia-app branch consumes.
Releases
Previous releases were formatted: v<CELESTIA_CORE_VERSION>-tm-v<COMETBFT_VERSION>.
For example: 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.
Recent releases after v0.39.0 do not include the CometBFT version.
