celestia-app

celestia-app is the software used by validators and consensus nodes on the Celestia consensus network. celestia-app is a blockchain application built using parts of the Cosmos stack:

• celestiaorg/cosmos-sdk a fork of cosmos/cosmos-sdk
• celestiaorg/celestia-core a fork of cometbft/cometbft

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

From source

1. Install Go 1.24.6

2. Clone this repo

3. Install the celestia-appd binary. This installs a "multiplexer" binary that will also download embedded binaries for the latest celestia-app v3.x.x and v4.x.x release.

   make install

Prebuilt binary

If you'd rather not install from source, you can download a prebuilt binary from the releases page.

1. Navigate to the latest release on https://github.com/celestiaorg/celestia-app/releases.

2. Download the binary for your platform (e.g. celestia-app_Linux_x86_64.tar.gz) from the Assets section. Tip: if you're not sure what platform you're on, you can run uname -a and look for the operating system (e.g. Linux, Darwin) and architecture (e.g. x86_64, arm64).

3. Extract the archive

   tar -xvf celestia-app_Linux_x86_64.tar.gz

4. Verify the extracted binary works

   ./celestia-appd --help

5. [Optional] verify the prebuilt binary checksum. Download checksums.txt and then verify the checksum:

   sha256sum --ignore-missing --check checksums.txt

   You should see output like this:

   celestia-app_Linux_x86_64.tar.gz: OK

See https://docs.celestia.org/how-to-guides/celestia-app for more information.

Usage

Warning

The celestia-appd binary doesn't support signing with Ledger hardware wallets on Windows and OpenBSD.

Prerequisites

If you are on Linux, enable the BBR ("Bottleneck Bandwidth and Round-trip propagation time") congestion control algorithm.

# Check if BBR is enabled (Linux only).
make bbr-check

# If BBR is not enabled then enable it (Linux only).
make bbr-enable

Environment variables

Variable	Explanation	Default value	Required
CELESTIA_APP_HOME	Where the application files should be saved.	$HOME/.celestia-app	Optional

Using celestia-appd

# Print help.
celestia-appd --help

# Create config files for a new chain named "test".
celestia-appd init test

# Start the consensus node.
celestia-appd start

Create a single node local testnet

# Start a single node local testnet.
./scripts/single-node.sh

# Publish blob data to the local testnet.
celestia-appd tx blob pay-for-blob 0x00010203040506070809 0x48656c6c6f2c20576f726c6421 \
	--chain-id test \
	--from validator \
	--keyring-backend test \
	--fees 21000utia \
	--yes

# Query the tx
celestia-appd query tx <txhash from previous command>

Join a public Celestia network

For instructions on running a node on Celestia's public networks, refer to the consensus node guide in the docs.

Note

When connecting to a public network, you must download the correct genesis file. Please use the celestia-appd download-genesis command.

Usage as a library

If you import celestia-app as a Go module, you may need to add some Go module replace directives to avoid type incompatibilities. Please see the replace directive in go.mod for inspiration.

Usage in tests

If you are running celestia-app in tests, you may want to override the delayed_precommit_timeout to produce blocks faster. By default, a celestia-app chain with app version >= 3 will produce blocks every ~6 seconds. To produce blocks faster, you can override the delayed_precommit_timeout with the --delayed-precommit-timeout flag.

# Start celestia-appd with a one-second block time.
celestia-appd start --delayed-precommit-timeout 1s

Server Architecture

celestia-app and celestia-core start multiple servers to handle different types of network communication and requests. Here's an overview of each server and their default addresses:

Celestia-Core (CometBFT) Servers

Server	Default Address	Configuration	Purpose
RPC	tcp://127.0.0.1:26657	config.toml under [rpc]	HTTP/WebSocket API for blockchain queries, transaction submission, and real-time event subscriptions.
gRPC	tcp://127.0.0.1:9098	config.toml under [rpc]	gRPC API for broadcasting txs, querying blocks, and querying blobstream data
P2P	tcp://0.0.0.0:26656	config.toml under [p2p]	Peer-to-peer networking layer for consensus, block synchronization, and mempool gossip.

Celestia-App (Cosmos SDK) Servers

Server	Default Address	Configuration	Purpose
gRPC	localhost:9090	app.toml under [grpc]	gRPC for application-specific queries. Provides access to Cosmos SDK modules (bank, governance, etc.) and Celestia-specific modules (blob).
REST API	tcp://localhost:1317	app.toml under [api]	RESTful HTTP API that proxies requests to the gRPC server via gRPC-gateway. Provides the same functionality as gRPC but over HTTP with JSON.
gRPC-Web	Uses REST API server address	app.toml under [grpc-web]	Browser-compatible gRPC API that allows web applications to interact with the gRPC server.

Contributing

If you are a new contributor, please read contributing to Celestia.

This repo attempts to conform to conventional commits so PR titles should ideally start with fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, or test: because this helps with semantic versioning and changelog generation. It is especially important to include an ! (e.g. feat!:) if the PR includes a breaking change.

This repo contains multiple go modules. When using it, rename go.work.example to go.work and run go work sync.

Tools

1. Install golangci-lint 2.1.2
2. Install markdownlint 0.39.0
3. Install hadolint
4. Install yamllint
5. Install markdown-link-check
6. Install goreleaser

Helpful Commands

# Get more info on make commands.
make help

# Build the celestia-appd binary into the ./build directory.
make build

# Build and install the celestia-appd binary into the $GOPATH/bin directory.
make install

# Run tests.
make test

# Format code with linters (this assumes golangci-lint and markdownlint are installed).
make lint-fix

# Regenerate Protobuf files (this assumes Docker is running).
make proto-gen

Docs

Package-specific READMEs aim to explain implementation details for developers that are contributing to these packages. The specs aim to explain the protocol as a whole for developers building on top of Celestia.

Dependency branches

The source of truth for dependencies is the go.mod file but the table below describes the compatible branches for celestiaorg repos.

celestia-app	celestia-core	cosmos-sdk
main	main	release/v0.51.x-celestia
v6.x	v0.39.x-celestia	release/v0.51.x-celestia
v5.x	v0.38.x-celestia	release/v0.50.x-celestia
v4.x	v0.38.x-celestia	release/v0.50.x-celestia
v3.x	v0.34.x-celestia	release/v0.46.x-celestia

Audits

Date	Auditor	Version	Report
2023/9/15	Informal Systems	v1.0.0-rc6	informal-systems.pdf
2023/10/17	Binary Builders	v1.0.0-rc10	binary-builders.pdf
2024/7/1	Informal Systems	v2.0.0-rc1	informal-systems-v2.pdf
2024/9/20	Informal Systems	306c587	informal-systems-authored-blobs.pdf
2025/6/24	Informal Systems	139bad2	informal-systems-recovery.pdf