hiero-ledger / hiero-ledger/hiero-consensus-node
CLPR-1: Network Layer — configure CLPR, connect to peer ledgers, manage trust
- Dominant language
- Java
- Stars
- 406
- Forks
- 226
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 210
Description
## Epic CLPR-1: Network Layer
**Parent:** hiero-ledger/roadmap#48
### Objective
Establish the on-ledger foundation for cross-ledger networking: ledger identity, configuration, peer connections, verifier trust, endpoint rosters, and misbehavior enforcement. This implements the Network Layer (§3.1) from the [CLPR Design Document](hedera-node/docs/design/services/clpr-service/clpr-service.md) on Hiero.
### Background
CLPR's Network Layer is the foundation everything else builds on. It defines how ledgers identify themselves, how Connections to peers are formed and governed, how verifier contracts provide the trust mechanism, and how misbehavior is detected and reported. A prototype exists with basic handlers (adoptPeerConfiguration, getLocalConfiguration, sync, processSyncResult) and simplified state (ClprLedgerId-keyed). This epic replaces the prototype with the full spec-compliant implementation using 32-byte Connection IDs, ECDSA registration, approved verifiers, and the complete connection lifecycle state machine.
### Expected Functionality
When this epic is complete:
1. **Ledger configuration** — An administrator can configure this ledger's CLPR identity (throttles, approved verifiers) and the configuration is stored in the Merkle state tree. Chain ID is immutable and determined at CLPR activation. Protocol version is determined by the code.
2. **Connection registration** — Anyone can register a Connection to a peer ledger using an ECDSA-derived Connection ID and an approved verifier contract, posting an anti-griefing deposit
3. **Connection governance** — The administrator can pause, resume, or permanently close any Connection
4. **Status state machine** — Connection status transitions (ACTIVE, PAUSED, CLOSED, HALTED) are enforced per the cross-platform spec §2.1.1
5. **Verifier management** — The Connection admin can update a Connection's verifier to a new approved contract; the Connection admin can update a stale peer endpoint roster via state proof
6. **Verifier trust enforcement** — When an approved verifier is removed or its code hash changes, all ACTIVE Connections using that verifier are automatically paused and cannot resume until updated
7. **Misbehavior reporting** — Misbehavior reports are delivered as control messages in bundles from the detecting ledger; the CLPR service validates evidence and applies penalties
8. **Queryable state** — Ledger configuration (including approved verifiers) is queryable via HAPI; Connection state is available via Mirror Node
9. **Tested end-to-end** — A Connection can be registered, governed, and verified from a test client
### Constraints
- Black-box testing only (no Mockito)
- CLPR admin key on Hiero is the 0.0.2 privileged key — never settable or rotatable via CLPR transactions
### Dependencies
None — this is the foundation epic.
### Spec References
- [CLPR Design Document §3.1](hedera-node/docs/design/services/clpr-service/clpr-service.md) — Network Layer architecture
- [CLPR Protocol Specification §1-3](hedera-node/docs/design/services/clpr-service/clpr-service-spec.md) — Wire formats, state model, verification
- [CLPR Hiero Implementation Spec §1-2](hedera-node/docs/design/services/clpr-service/clpr-hiero-impl-spec.md) — HAPI transactions, state schema, handler details
Contributor guide
Research direction
Start with hedera-node/docs/design/services/clpr-service/clpr-service.md, then read clpr-service-spec.md and clpr-hiero-impl-spec.md for the Network Layer state model, wire formats, and HAPI handlers. Map the existing prototype handlers and state before taking a scoped part of this epic. Done means the selected Network Layer functionality is implemented, black-box tested, and supports the specified connection lifecycle and trust rules.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- backend-api-design, distributed-systems, networking
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100