This file defines the minimum rules for AI agents working on Tenderdash. It does not duplicate details from the style guide; instead, it references the source.
Follow the rules in STYLE_GUIDE.md. Do not duplicate them here or in other
agent configuration files.
- Ensure all changed code passes the linter.
- Ensure the code is thread-safe. Check memory leaks, deadlocks and race conditions.
- Review implementation to find any security issues. Identify and verify edge cases. Check known security issues.
- If unsure, explicitly report any potential security issues, gaps, missing features and TODO items.
Key directories:
abci/– Application BlockChain Interface (app ↔ consensus boundary)cmd/– CLI/binary entrypointsconfig/– configuration structs, defaults, and config testscrypto/– cryptographic primitives and key handlingdash/– Dash-specific components (quorums, validators, etc.)docs/– documentationinternal/– internal (unexported) packageslibs/– shared utility librariesnode/– node setup, lifecycle, and reactor wiringproto/– protobuf definitions (source of truth for wire types)rpc/– JSON-RPC server and clientspec/– protocol specificationtypes/– domain types (Block, Vote, Commit, etc.)test/– integration tests and test supporttools/,scripts/– helper tools and automation scripts
Do not edit generated files (e.g. *.pb.go). Edit the .proto source
and regenerate with make proto-gen.
# Build the BLS native library: inits the submodule, needs cmake, a C++
# compiler and libgmp-dev. Once per checkout or worktree.
make build-bls
# Build (includes build-bls)
make build
# Run all unit tests (-p 1, -tags deadlock)
make test
# Run all unit tests with race detector (-p 1)
make test_race
# Lint lines changed vs origin/dev (what CI enforces);
# stacked PRs: make lint LINT_BASE=origin/<base-branch>
make lint
# Format
make formatMost packages link BLS through cgo. The Makefile passes the cgo flags only to
its own targets, so a bare go test, go vet or go build fails with:
blschia.cpp:17:10: fatal error: dashbls/bls.hpp: No such file or directory
Export the Makefile's flags once per shell, then run go directly:
BLS_DIR="$(git rev-parse --show-toplevel)/third_party/bls-signatures"
export CGO_ENABLED=1
export CGO_CXXFLAGS="-I$BLS_DIR/build/depends/relic/include -I$BLS_DIR/src/depends/mimalloc/include -I$BLS_DIR/src/depends/relic/include -I$BLS_DIR/src/include"
export CGO_LDFLAGS="-L$BLS_DIR/build/depends/mimalloc -L$BLS_DIR/build/depends/relic/lib -L$BLS_DIR/build/src -ldashbls -lrelic_s -lmimalloc-secure -lgmp"
go test -race -count=1 -run 'TestName' ./internal/p2p/third_party/bls-signatures/build/exists only wheremake build-blsran. In a fresh clone or a newgit worktree, run it there, or setBLS_DIRto another checkout that already built the same BLS revision.- macOS: append
-L$(brew --prefix gmp)/libtoCGO_LDFLAGSand-I$(brew --prefix gmp)/includetoCGO_CXXFLAGS, as the Makefile does. - CI (
.github/workflows/tests.yml) installs BLS into/usr/localand runsgo test -race -timeout=5mover package groups (make test-group-N NUM_SPLIT=6). cmd/abcidumpneedslibpcap-dev.-count=1bypasses the Go test cache when re-running unchanged tests.
- Go dependencies are managed via Go Modules. Only update required modules.
- To review newer versions:
go list -u -m all. - If build issues arise, use
go mod tidy. - Protobufs:
bufandgogoprotoare required.- Lint:
make proto-lint - Breaking changes:
make proto-check-breaking - Generation:
make proto-gen - Formatting:
make proto-format(requiresclang-format)
- Lint:
devis the integration branch;masteris the latest stable Dash Platform release line.- Do all development on
dev: create feature branches fromorigin/devand open PRs intodev. The only exception is a stable hotfix, which branches frommasterand is forward-ported todev. - Versioned
vX.Y-devbranches (e.g.v1.8-dev,v1.9-dev) are retired. Never branch from, target, or compare against them, even if one still exists on the remote. - Keep commits focused and well-described.
- Use conventional commit format for commit and PR titles.
- Do not manually edit or generate
CHANGELOG.mdfor development changes. The project release skill prepares it only for a requested release. - PR descriptions: read
.github/PULL_REQUEST_TEMPLATE.md, fill in every section, base content on the full diff against the target branch. - AI code review (
.github/workflows/claude-code-review.yml) is opt-in: maintainers trigger it via theclaudius-reviewlabel. SeeCONTRIBUTING.mdfor the review process.
- Private keys and configuration files containing keys are secret: do not log them or commit them to the repo.
- Particularly sensitive files:
config/priv_validator_key.json,config/node_key.json, TLS keys (tls-key-filein config).
- BLS native dependency must be built before Go binaries (
make buildhandles this); standalonegocommands need the cgo flags from Running targeted tests. *.pb.gofiles are generated — never edit them by hand.gogoprotoextensions (e.g.,nullable,customtype) can produce unexpected Go types; always check the generated code after proto changes.- Some packages under
internal/importdash/types; be mindful of import cycles when moving code between packages.
Tenderdash is supported as a component of Dash Platform development, not as an independent consensus product with a fixed minor-version support window. Use tenderdash-release for release analysis or a requested release. Read the actual history and diffs before selecting SemVer; a normal development task does not authorize publication. See RELEASES.md for release preparation and coordinated rollout.