Orchestration tooling for the F1R3FLY blockchain ecosystem. Manages multiple service repositories with Docker Compose and the shardctl CLI.
- Python 3.10+ (pyenv setup if your system Python is newer)
- Poetry —
pipx install poetryorpip install --user poetry - Docker & Docker Compose
poetry install # Installs shardctlFor per-service build toolchains (Rust, SBT, Node), see docs/setup.md.
poetry run shardctl up f1r3node-rust
poetry run shardctl waitGenesis takes ~2-3 minutes. shardctl wait blocks until all nodes report Running.
poetry run shardctl statusHTTP API endpoints once Running: bootstrap on port 40403, validator1 on 40413, etc. Full port map in COMPOSE_STRUCTURE.md.
poetry run shardctl down # Stop containers
poetry run shardctl reset -y # Stop and wipe data volumesNo Poetry? You can run shards directly with Docker Compose:
docker compose --env-file .env.node -f compose/f1r3node-rust.yml up -d docker compose --env-file .env.node -f compose/f1r3node-rust.yml logs -f docker compose --env-file .env.node -f compose/f1r3node-rust.yml down -v # stop + wipe
| Goal | Doc |
|---|---|
| Different topology (Scala, standalone, observer, validator4, light shard) | COMPOSE_STRUCTURE.md |
| Custom node Docker image | COMPOSE_STRUCTURE.md#image-selection |
| Full multi-service setup (clone all repos, build images, start everything) | docs/setup.md#full-multi-service-setup |
Every shardctl command + flag |
docs/cli-reference.md |
| Node configs + env files | docs/configuration.md |
| Consensus parameters (FTT, synchrony) | docs/consensus-configuration.md |
| Monitoring (Prometheus + Grafana) | COMPOSE_STRUCTURE.md#monitoring-stack |
| Run integration tests | integration-tests/README.md |
| Native services (F1R3Drive FUSE) | docs/f1r3drive-guide.md |
| Slashing | docs/slashing-mechanism.md |
| Troubleshooting | docs/troubleshooting.md |
| Development workflow | docs/development.md |
See CLAUDE.md for the full directory layout.
- Only commit changes to integration tooling (compose files, shardctl code, docs)
- Never commit service code (it belongs in service repos under
services/) - CI runs automatically on PRs (compose validation, topology health, integration tests)
- Update relevant docs when adding features
For development workflow and best practices, see docs/development.md.
MIT License — see LICENSE file for details