hiero-ledger / hiero-ledger/hiero-consensus-node
CLPR-4: Hiero Endpoint — peer-to-peer sync, proof construction, and bundle submission
- Dominant language
- Java
- Stars
- 406
- Forks
- 226
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 210
Description
## Epic CLPR-4: Hiero Endpoint
**Parent:** hiero-ledger/roadmap#48
**Repo:** hiero-ledger/hiero-consensus-node
### Objective
Implement the Hiero Endpoint module: the peer-to-peer sync orchestration layer that runs within each consensus node. Covers gRPC server/client, proof construction from Merkle state, sync scheduling, bundle submission, and automatic endpoint roster derivation.
### Background
Every consensus node IS a CLPR endpoint when CLPR is enabled. There is no separate process, sidecar, or external service. The endpoint module bridges the on-ledger CLPR Service with peer ledgers by constructing state proofs, orchestrating sync calls, and submitting received bundles as `ClprSubmitBundle` transactions through `SubmissionManager` (bypassing `IngestWorkflow`).
### Expected Functionality
1. **gRPC server** — `ClprEndpointService` with mTLS, accepting inbound sync calls.
2. **Proof construction** — `ClprStateProofManager` constructs proofs from latest immutable (TSS-signed) state.
3. **Sync orchestration** — `ClprConnectionManager` triggers outbound syncs when pending messages exist, with reputation-weighted peer selection.
4. **Bundle submission** — Received payloads pre-verified locally, then submitted as `ClprSubmitBundle` via `SubmissionManager`.
5. **Roster derivation** — `RosterObserver` derives local endpoint roster from active consensus roster. Changes trigger `EndpointJoin`/`EndpointLeave` control messages.
### Constraints
- Built into the Hiero consensus node JVM process
- Must use latest immutable (TSS-signed) state, never working state
- Max concurrent syncs configurable (default 4), per-Connection max 1 outbound
- Duplicate submissions are protocol-correct (only first succeeds); heuristics reduce waste
### Stories
- CLPR-4.1: gRPC server and ClprEndpointService
- CLPR-4.2: Proof construction from Merkle state
- CLPR-4.3: Sync orchestration and peer selection
- CLPR-4.4: Bundle submission pipeline
- CLPR-4.5: Automatic endpoint roster derivation
### Dependencies
- CLPR-2 (SubmitBundle handler)
- Existing infrastructure: gRPC/Netty, State API, StateProofBuilder, MerklePathBuilder, SubmissionManager, RosterService, TSS, Dagger, ConfigProvider
### Spec References
- [Hiero Endpoint Spec](clpr-hiero-endpoint-spec.md)
Contributor guide
Research direction
Start with clpr-hiero-endpoint-spec.md and the listed CLPR-2 dependency and existing entry points: StateProofBuilder, MerklePathBuilder, SubmissionManager, RosterService, and ConfigProvider. Break the work into the five named stories, from ClprEndpointService through RosterObserver, before choosing a scoped implementation task. Done requires the gRPC, proof, sync, submission, and roster functionality described in the objective and constraints.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- grpc, java
- Domain
- backend-api-design, distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100