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

CLPR-1: Network Layer — configure CLPR, connect to peer ledgers, manage trust

Open
#24,484 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-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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.