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

CLPR-2: Messaging Layer — reliable, ordered message delivery between ledgers

Open
#24,514 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
407
Forks
226
Avg merge
3d 4h
Merged PRs (30d)
210

Description

## Epic CLPR-2: Messaging Layer

**Parent:** hiero-ledger/roadmap#48
**Repo:** hiero-ledger/hiero-consensus-node

### Objective

Implement reliable, ordered message delivery between ledgers on Hiero: message enqueue, bundle verification, running hash integrity, response ordering, message redaction, and lazy configuration propagation.

### Background

The Messaging Layer provides the core transport primitive. Messages are enqueued on the source ledger, bundled and transmitted via endpoint sync, verified at consensus on the destination, and responses flow back. A SHA-256 running hash chain ensures integrity. Response ordering verification detects peer-side bugs and HALTs affected Connections.

`sendMessage` is a **system contract method** — it is called by application smart contracts, not via HAPI. `submitBundle` is a **HAPI transaction** — it is submitted by endpoint nodes through consensus. `redactMessage` is a **HAPI transaction** — it is an admin operation.

### Expected Functionality

When this epic is complete:

1. **Message enqueue** — `sendMessage` (system contract) enqueues a message on an ACTIVE Connection with a sequential ID and extended running hash.
2. **Bundle verification** — `submitBundle` (HAPI) verifies inbound bundles (proof via verifier contract, replay defense, running hash, size limits) and dispatches each message by type.
3. **Control message processing** — `ConfigUpdate`, `EndpointJoin`, `EndpointLeave` applied directly to local state. No responses generated.
4. **Response ordering** — Incoming Response Messages are verified against the oldest unresponded Data Message. Ordering violations transition the Connection to HALTED.
5. **Message redaction** — `redactMessage` (HAPI, admin) removes a message's payload while preserving the slot and running hash for chain integrity.
6. **Lazy config propagation** — Configuration changes are enqueued as Control Messages on-demand when traffic flows, not eagerly.
7. **Queue depth enforcement** — `next_message_id - acked_message_id < max_queue_depth`.

### Constraints

- Black-box testing only
- Running hash: `SHA-256(previous_hash || canonical_protobuf_serialization)`, initialized to `32×0x00`
- Control Messages do not generate responses
- Bad bundles (failed verification) are rejected with no state change; only response ordering violations trigger HALT

### Stories

- CLPR-2.1: Messaging wire formats, state schema, and system contract interface
- CLPR-2.2: sendMessage (system contract method)
- CLPR-2.3: submitBundle (HAPI transaction handler)
- CLPR-2.4: Response ordering and HALT detection
- CLPR-2.5: Message redaction
- CLPR-2.6: Lazy configuration propagation

### Dependencies

- CLPR-1 (Network Layer — Connections, verifiers, endpoint rosters)

### Spec References

- [Cross-Platform Spec §4](clpr-service-spec.md) — Algorithms (running hash, bundle verification, enqueue, response ordering)
- [Hiero Impl Spec §3.2](clpr-hiero-impl-spec.md) — Handler details for SubmitBundle and SendMessage

Contributor guide

Open the contributing guide

Research direction

Start with clpr-service-spec.md §4 and clpr-hiero-impl-spec.md §3.2, then review the CLPR-1 dependency and the six listed stories. Done means implementing and black-box testing the full messaging layer, including enqueueing, bundle verification, ordering and HALT handling, redaction, lazy configuration propagation, and queue limits.

Written by the indexing model from the issue text.

Assessment

Tech stack
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.