README
¶
chaincoord
Self-hosted coordination server for Cosmos SDK chain launches — M-of-N committee governance, a guarded launch-lifecycle state machine, gentx intake with pre-acceptance validation, and a tamper-evident, offline-verifiable audit log.
chaincoord is the coordination server (coordd) in Seedward, the self-hostable operator suite I'm
building for the Cosmos SDK chain lifecycle. Its siblings:
- seedward-gentool — deterministic genesis-file construction (also the engine
rehearsalembeds) - seedward-rehearsal — a pre-flight service that boots a throwaway chain to prove a genesis initializes and advances before anyone commits
- seedward-cli — the unified suite CLI (planned, post-v1; its coordd-facing commands are stubs today)
- pour — a pure-Go multi-chain faucet
Published components are Apache-2.0 and self-hostable.
Spec-Driven Development (SDD) project. The design is mine — the protocol, the M-of-N committee governance model, the launch-lifecycle state machine, the threat model, and the offline-verifiable audit-log security design — authored as a spec and then implemented with AI assistance under my review. The result is a complete, capable v1 — not production-ready yet, but built to get there with real-world testing.
📖 Full documentation · 🏗️ Design document
What it does
Launching a Cosmos SDK chain means assembling a genesis file from validator contributions, reaching M-of-N agreement on its content, and making sure every participant starts from the same file at the same time. Done informally — over chat or shared drives — that's error-prone and unaccountable.
coordd makes it explicit, auditable, and multi-party: every lifecycle transition
(DRAFT → PUBLISHED → WINDOW_OPEN → WINDOW_CLOSED → GENESIS_READY → LAUNCHED) is driven by a committee
proposal requiring M-of-N coordinator signatures, and every action lands in a signed, offline-verifiable
audit log. See the concepts overview
for the full model.
Scope: Cosmos SDK chains only (secp256k1, gentx-based genesis, CometBFT RPC). coordd never runs a
chain node, never holds a private key (signing is client-side), and never assembles the final genesis — the
coordinator builds that locally with the chain binary (<chaind> genesis collect-gentxs). SQLite by
default; storage and RPC layers are interface-backed.
Quick start
coordd is a headless coordination server — it has no UI of its own. Two ways to run it:
- The server alone (this repo). Run the published image from GHCR — the
Run with Docker guide has
the
keygen → migrate → servesequence and env reference — or build locally withmake build(see the Quickstart). - The full stack — coordd + the web UI, one command. That lives in
seedward-suite (
make dev-upruns both). The web front end on its own is seedward-chaincoord-web.
Health check once it's up: curl http://localhost:8080/healthz → {"status":"ok"}. For TLS and production
configuration, see Setup & Configuration.
Documentation
Full docs: https://ny4rl4th0t3p.github.io/seedward-chaincoord/
- Getting started — Quickstart · Run with Docker · Smoke test
- Concepts — overview: roles, lifecycle, proposals, genesis, readiness, trust model
- Reference — setup & config · API · audit CLI
- Decisions — the ADR-style record
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
coordd
command
@title ChainCoord API @version 1.0 @description Chain launch coordination server.
|
@title ChainCoord API @version 1.0 @description Chain launch coordination server. |
|
smoke-signer
command
|
|
|
internal
|
|
|
application/ports
Package ports defines the interfaces (ports) that the application layer depends on.
|
Package ports defines the interfaces (ports) that the application layer depends on. |
|
application/services
Package services contain the application-layer use cases.
|
Package services contain the application-layer use cases. |
|
domain
Package domain defines the shared domain event types emitted by aggregates.
|
Package domain defines the shared domain event types emitted by aggregates. |
|
domain/joinrequest
Package joinrequest contains the JoinRequest aggregate.
|
Package joinrequest contains the JoinRequest aggregate. |
|
domain/launch
Package launch contains the Launch aggregate and its owned entities.
|
Package launch contains the Launch aggregate and its owned entities. |
|
domain/proposal
Package proposal contains the Proposal aggregate, which collects M-of-N committee member signatures and executes actions when quorum is reached.
|
Package proposal contains the Proposal aggregate, which collects M-of-N committee member signatures and executes actions when quorum is reached. |
|
infrastructure/api
Package api contains the HTTP handler layer.
|
Package api contains the HTTP handler layer. |
|
infrastructure/auditlog
Package auditlog implements ports.AuditLogWriter as an append-only JSONL file.
|
Package auditlog implements ports.AuditLogWriter as an append-only JSONL file. |
|
infrastructure/auth
Package auth provides JWT-based session management for coordd.
|
Package auth provides JWT-based session management for coordd. |
|
infrastructure/gentxvalidation
Package gentxvalidation adapts the shared seedward-libs/gentxvalidate library to the ports.GentxValidator interface, keeping the SDK/validation weight out of the domain and application layers.
|
Package gentxvalidation adapts the shared seedward-libs/gentxvalidate library to the ports.GentxValidator interface, keeping the SDK/validation weight out of the domain and application layers. |
|
infrastructure/jobs
Package jobs contains background goroutines that run for the lifetime of the server process.
|
Package jobs contains background goroutines that run for the lifetime of the server process. |
|
infrastructure/sse
Package sse implements a simple fan-out broker for Server-Sent Events.
|
Package sse implements a simple fan-out broker for Server-Sent Events. |
|
infrastructure/storage/sqlite
Package sqlite implements the storage ports using SQLite via modernc.org/sqlite.
|
Package sqlite implements the storage ports using SQLite via modernc.org/sqlite. |
|
netutil
Package netutil provides network-related utilities for server-side validation.
|
Package netutil provides network-related utilities for server-side validation. |