|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +celestia-app is the blockchain application for the Celestia consensus network. It is built on forks of Cosmos SDK (`celestiaorg/cosmos-sdk`) and CometBFT (`celestiaorg/celestia-core`). The current major version is v6 (module path: `github.com/celestiaorg/celestia-app/v6`). |
| 8 | + |
| 9 | +## Build and Development Commands |
| 10 | + |
| 11 | +```sh |
| 12 | +# Build binary (multiplexer mode, downloads embedded v3/v4/v5 binaries) |
| 13 | +make build |
| 14 | + |
| 15 | +# Build without downloading embedded binaries |
| 16 | +DOWNLOAD=false make build |
| 17 | + |
| 18 | +# Build standalone (no multiplexer) |
| 19 | +make build-standalone |
| 20 | + |
| 21 | +# Install binary |
| 22 | +make install |
| 23 | + |
| 24 | +# Run all tests (30m timeout) |
| 25 | +make test |
| 26 | + |
| 27 | +# Run tests in short mode (1m timeout) |
| 28 | +make test-short |
| 29 | + |
| 30 | +# Run a single test |
| 31 | +go test -run TestName -timeout 30m ./path/to/package/... |
| 32 | + |
| 33 | +# Run a single test in a specific package |
| 34 | +go test -run TestName -timeout 30m ./x/blob/... |
| 35 | + |
| 36 | +# Lint (requires golangci-lint, markdownlint, hadolint, yamllint) |
| 37 | +make lint |
| 38 | + |
| 39 | +# Auto-fix lint issues |
| 40 | +make lint-fix |
| 41 | + |
| 42 | +# Run golangci-lint only |
| 43 | +golangci-lint run |
| 44 | + |
| 45 | +# Regenerate Protobuf files (requires Docker) |
| 46 | +make proto-gen |
| 47 | + |
| 48 | +# Update go.mod files |
| 49 | +make mod |
| 50 | + |
| 51 | +# Docker e2e tests (requires test name) |
| 52 | +make test-docker-e2e test=TestE2ESimple |
| 53 | +``` |
| 54 | + |
| 55 | +## Multi-Module Workspace |
| 56 | + |
| 57 | +This repo contains multiple Go modules. Copy `go.work.example` to `go.work` and run `go work sync` for local development. The secondary module is in `test/docker-e2e/` with its own `go.mod`. |
| 58 | + |
| 59 | +## Architecture |
| 60 | + |
| 61 | +### Application Layer (`app/`) |
| 62 | + |
| 63 | +- `app.go` - Main `App` struct extending `baseapp.BaseApp`. Contains all module keepers, store keys, and wiring. |
| 64 | +- `modules.go` - Module manager setup and module ordering (begin/end blockers, init genesis order). |
| 65 | +- `prepare_proposal.go` / `process_proposal.go` - ABCI++ block proposal logic (square construction and validation). |
| 66 | +- `ante/` - Ante handler chain (fee deduction, signature verification, tx size gas, blob-specific validation). |
| 67 | +- `upgrades.go` - On-chain upgrade handlers for version transitions. |
| 68 | + |
| 69 | +### Custom Cosmos SDK Modules (`x/`) |
| 70 | + |
| 71 | +- `x/blob` - Pay-for-blob transaction type. Core Celestia module enabling data availability. |
| 72 | +- `x/signal` - Coordinates network upgrades by tracking validator version signals. Ensures all validators upgrade before the chain transitions to a new app version. |
| 73 | +- `x/mint` - Custom inflation/minting module. |
| 74 | +- `x/minfee` - Global minimum gas price enforcement. |
| 75 | + |
| 76 | +### Multiplexer (`multiplexer/`) |
| 77 | + |
| 78 | +An upgrade system that enables syncing from genesis and seamless chain upgrades without switching binaries. It embeds older version binaries (v3, v4, v5) and manages the lifecycle of standalone processes via gRPC ABCI connections. The multiplexer sits between CometBFT and the application, watching for `AppVersion` changes to trigger automatic upgrades. |
| 79 | + |
| 80 | +### Public Packages (`pkg/`) |
| 81 | + |
| 82 | +- `pkg/appconsts` - Network constants (share sizes, square sizes, versioned parameters). |
| 83 | +- `pkg/user` - Transaction signing and broadcasting client (`TxClient`). |
| 84 | +- `pkg/proof` - Share and namespace Merkle proof generation/verification. |
| 85 | +- `pkg/inclusion` - Blob inclusion proof logic. |
| 86 | +- `pkg/wrapper` - Erasure-coded data square wrapper using NMT (Namespace Merkle Tree). |
| 87 | +- `pkg/da` - Data availability header utilities. |
| 88 | + |
| 89 | +### Testing (`test/`) |
| 90 | + |
| 91 | +- `test/txsim/` - Transaction simulator sequences (blob, send, stake, upgrade) used in e2e tests. |
| 92 | +- `test/docker-e2e/` - Docker-based end-to-end tests (separate Go module). Includes upgrade, IBC, state sync, and block sync tests. |
| 93 | +- `test/util/` - Test utilities including testnode setup for integration tests. |
| 94 | +- `app/test/` - Integration tests for the application (uses testnode). |
| 95 | + |
| 96 | +### Tools (`tools/`) |
| 97 | + |
| 98 | +Various operational tools: `chainbuilder`, `blocktime`, `throughput`, `blockscan`, `talis` (deployment), etc. |
| 99 | + |
| 100 | +## Conventions |
| 101 | + |
| 102 | +- Follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for PR titles: `fix:`, `feat:`, `refactor:`, `chore:`, etc. Use `!` for breaking changes (e.g., `feat!:`). |
| 103 | +- Use `testify/assert` and `testify/require` for test assertions. Prefer table-driven tests. |
| 104 | +- Go 1.24.6 is required. |
| 105 | +- golangci-lint 2.1.2 is the expected linter version. |
| 106 | + |
| 107 | +## Key Dependencies |
| 108 | + |
| 109 | +| Dependency | Branch | |
| 110 | +|---|---| |
| 111 | +| `celestiaorg/cosmos-sdk` | `release/v0.51.x-celestia` | |
| 112 | +| `celestiaorg/celestia-core` | `main` | |
| 113 | +| `cosmos/ibc-go` | v8 | |
0 commit comments