celestia-app

README

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

Source

1. Install Go 1.23.1

2. Clone this repo

3. Install the celestia-app CLI

   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/nodes/celestia-app for more information.

Usage

First, make sure that the BBR ("Bottleneck Bandwidth and Round-trip propagation time") congestion control algorithm is enabled in the system's kernel. The result should contain bbr:

sysctl net.ipv4.tcp_congestion_control

If not, enable it on Linux by calling the make use-bbr or by running:

sudo modprobe tcp_bbr
net.core.default_qdisc=fq
net.ipv4.tcp_congestion_control=bbr
sudo sysctl -p

# Print help
celestia-appd --help

Environment variables

Variable	Explanation	Default value	Required
CELESTIA_HOME	Where the application directory (.celestia-app) should be saved	User home directory	Optional

Create your own single node devnet

# Start a single node devnet
./scripts/single-node.sh

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

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

Usage as a library

If 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.

Contributing

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 1.61.0
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 fmt

# 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.

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