hiero-ledger / hiero-ledger/hiero-consensus-node
CLPR-2: Messaging Layer — reliable, ordered message delivery between ledgers
- 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
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