hiero-ledger / hiero-ledger/hiero-consensus-node

CLPR-4: Hiero Endpoint — peer-to-peer sync, proof construction, and bundle submission

Open
#24,533 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.