iguazu-coordinator

Apache 2.0 sidecar binary for the Iguazu network. Runs alongside the Prysm-based coordinator node (GPL-3.0) and owns all asynchronous Iguazu-specific work — starting with the DAG finalization loop.
iguazu-coordinator has zero dependency on coordinator / Prysm code. It communicates with the coordinator exclusively over gRPC, which makes the two processes a "mere aggregation" under GPL-3.0 §5.
Architecture
coordinator (GPL-3.0) iguazu-coordinator (Apache 2.0)
┌───────────────────────┐ ┌────────────────────────────┐
│ beacon-chain node │ │ cmd/main.go │
│ │◄─────►│ finalization/service.go │
│ CoordinatorInternal │ gRPC │ StreamNewHeads │
│ gRPC service: │ │ GetFinalizationParams │
│ StreamNewHeads │ │ SubmitFinalizationResult │
│ GetFinalizationParams│ │ │
│ SubmitFinalization │ │ finalization/dag_client.go│
│ Result │ │ dag_finalize (JSON-RPC) │
└───────────────────────┘ └──────────┬─────────────────┘
│ HTTP JSON-RPC
┌──────▼──────┐
│ gwat / iguazu-engine │
└─────────────┘
DAG finalization loop
- Subscribe to
StreamNewHeads on startup.
- For each new canonical head received from the coordinator:
- Call
GetFinalizationParams(block_root) → receive FinalizationParamsResponse.
- Call gwat
dag_finalize with the params.
- Call
SubmitFinalizationResult with the gwat outcome so the coordinator can cache the new gwat coordinated checkpoint.
- On any error: log and reconnect after 5 s.
Package layout
iguazu-coordinator/
├── cmd/
│ └── main.go # CLI entry point
├── finalization/
│ ├── dag_client.go # gwat JSON-RPC client (dag_finalize, dag_coordinatedState)
│ ├── service.go # DAG finalization loop
│ └── service_test.go
└── proto/
└── coordpb/
├── coordinator_internal.pb.go # proto message types (Apache 2.0 copy)
└── coordinator_internal_grpc.pb.go # gRPC client bindings
Build
go build -o iguazu-coordinator ./cmd/
Requires Go 1.21+.
Run
./iguazu-coordinator \
--coordinator-grpc localhost:4000 \
--gwat-http http://localhost:8545 \
--log-level info
| Flag |
Env var |
Default |
Description |
--coordinator-grpc |
WF_COORDINATOR_GRPC |
localhost:4000 |
Coordinator gRPC endpoint (host:port or unix:///path) |
--gwat-http |
WF_GWAT_HTTP |
http://localhost:8545 |
gwat JSON-RPC HTTP endpoint |
--log-level |
WF_LOG_LEVEL |
info |
Log level: trace, debug, info, warn, error |
The process exits cleanly on SIGINT / SIGTERM.
Test
go test ./...
Dependencies
| Module |
License |
Role |
github.com/LFDT-Iguazu/iguazu-types |
Apache 2.0 |
dag finalization types (dag_finalize params/result) |
google.golang.org/grpc |
Apache 2.0 |
gRPC transport |
google.golang.org/protobuf |
BSD-3-Clause |
protobuf runtime |
github.com/sirupsen/logrus |
MIT |
structured logging |
github.com/urfave/cli/v2 |
MIT |
CLI flag parsing |
github.com/pkg/errors |
BSD-2-Clause |
error wrapping |
No dependency on coordinator, gwat or any other GPL/LGPL code. gwat is reached only over
JSON-RPC (dag_finalize, dag_coordinatedState) by a minimal client built on net/http.
Proto contract
The gRPC service is defined in coordinator/proto/prysm/v1alpha1/coordinator_internal.proto (Apache 2.0).
The generated Go code is vendored into proto/coordpb/ so this module stays self-contained.
Service name on the wire: ethereum.eth.v1alpha1.CoordinatorInternal
| Repository |
License |
Role |
coordinator |
GPL-3.0 |
Prysm-based beacon node; exposes CoordinatorInternal gRPC |
gwat |
LGPL-3.0 |
Execution layer; exposes dag_finalize JSON-RPC |
iguazu-engine |
Apache 2.0 |
Engine host that loads gwat as a runtime plugin |
iguazu-consensus |
Apache 2.0 |
Pure Iguazu consensus library |
iguazu-types |
Apache 2.0 |
Shared types and interfaces |
Releases
Releases are published as GitHub Releases with signed provenance;
see RELEASE.md for the process and how to verify them, and CHANGELOG.md
for the changes. Use the module with:
go get github.com/LFDT-Iguazu/iguazu-coordinator@latest
Documentation
API documentation is available on pkg.go.dev.
Adopters
If you use Iguazu, please add yourself to ADOPTERS.md.
Contributing
Iguazu is an LF Decentralized Trust project. See
CONTRIBUTING.md for how to contribute, MAINTAINERS.md for
the maintainers, SECURITY.md for reporting vulnerabilities and
CODE_OF_CONDUCT.md for the Code of Conduct.
License
Apache License 2.0 — see LICENSE.