hiero-ledger / hiero-ledger/hiero-consensus-node
CLPR-1.1: Define wire formats, state schema, and store implementations for the network layer
- Dominant language
- Java
- Stars
- 406
- Forks
- 226
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 210
Description
## Story CLPR-1.1: Network Layer Foundation
**Parent Epic:** #24484 (CLPR-1: Network Layer)
### Objective
Define all protobuf wire formats, the on-ledger state schema, and store interfaces required by the network layer. When this story is complete, all downstream handler stories can compile and build against stable types.
### Acceptance Criteria
- **AC-1:** Protobuf transaction bodies defined for 5 network-layer HAPI transactions: `ClprSetLedgerConfigurationTransactionBody`, `ClprRegisterConnectionTransactionBody`, `ClprCloseConnectionTransactionBody`, `ClprHaltConnectionTransactionBody`, `ClprResumeConnectionTransactionBody`. Of these, `RegisterConnection` is also exposed as a CLPR system contract method. The admin-only operations are HAPI only.
- **AC-2:** `ClprSetLedgerConfigurationTransactionBody` contains the `ClprLedgerConfiguration` to set. The handler auto-sets `protocol_version`, `chain_id` (immutable after activation), and `timestamp`. Caller-supplied values for these fields are ignored.
- **AC-3:** `ClprRegisterConnectionTransactionBody` includes: `connection_id` (bytes(32)), `ecdsa_signature` (bytes), `ecdsa_public_key` (bytes, 64-byte uncompressed x||y), `verifier_contract` (AccountID, immutable), and `config_proof_bytes` (bytes, passed to `verifyConfig()` to obtain verified peer configuration at registration time). Does NOT include `chain_id`, `service_address`, or `seed_endpoints` — `chain_id` and `service_address` are derived from the verified peer config proof; peer endpoint discovery is handled off-chain via gossip.
- **AC-4:** Protobuf query/response defined: `ClprGetLedgerConfigurationQuery/Response`. This is the only HAPI query in CLPR. Other read operations (`getConnector`) are system contract `view` functions.
- **AC-5:** State messages defined:
- `ClprLedgerConfiguration` (with `ClprThrottles` sub-message and `seed_endpoints` field for up to 10 peer bootstrap endpoints)
- `ClprConnection` (with `verifier_contract` (AccountID), `verifier_fingerprint` (bytes, informational keccak256 of bytecode), `chain_id`, `service_address`, `peer_config_timestamp`, `status`, `last_config_timestamp`, outbound queue metadata (`next_message_id`, `acked_message_id`, `sent_running_hash`), inbound queue metadata (`received_message_id`, `received_running_hash`))
- `ClprConnectionStatus` enum: `ACTIVE = 0`, `HALTED = 1`, `CLOSED = 2`
- `ClprEndpoint` (used for seed endpoints and gossip discovery)
- **AC-6:** Control message protos: `ClprControlMessage` oneof with `ConfigUpdate` only. Peer endpoint discovery is off-chain via gossip (cross-platform spec §5.4).
- **AC-7:** `TransactionBody` oneof extended with all 5 network-layer types. `Query`/`Response` oneofs extended with `ClprGetLedgerConfiguration`.
- **AC-8:** State schema defines network-layer stores: `LEDGER_CONFIGURATION` singleton, `LOCAL_LEDGER_METADATA` singleton, `CONNECTIONS` K/V (connection_id → ClprConnection). No `PEER_ENDPOINT_ROSTERS` store — peer endpoint data is not stored in state.
- **AC-9:** Readable/Writable store interfaces for connections.
- **AC-10:** All MATS pass with the new types.
### Notes
- HAPI transaction bodies for messaging (SubmitBundle, RedactMessage) and payment (RegisterConnector, etc.) are deferred to CLPR-2.1 and CLPR-3.1 respectively. `sendMessage` is a system contract method only (not a HAPI transaction) — defined in CLPR-2.1.
- The `ClprEndpoint` and `ServiceEndpoint` messages already exist in the prototype and can be reused.
- Connection state queries are handled by Mirror Node, not by HAPI queries.
- Lazy config propagation uses timestamp comparison (`last_config_timestamp` vs `consensus_timestamp`).
- There is no approved verifiers map — verifiers are specified per-Connection at registration and are immutable.
- There is no deposit/registrant tracking on Connections.
- Peer endpoint data is NOT stored in state. Discovery is off-chain via gossip.
- Connection has 3 states: ACTIVE, HALTED, CLOSED. No separate PAUSED state — HALTED serves both admin-initiated and protocol-triggered suspension.
### Dependencies
None — this is the first story in CLPR-1.
### Risk
**Medium** — Proto changes affect code generation across modules. MATS verification (AC-10) catches breakage early.
Contributor guide
Research direction
Start by locating the prototype ClprEndpoint and ServiceEndpoint messages, then inspect the existing TransactionBody, Query, and Response oneofs and store interface patterns. Run the MATS mentioned in AC-10 after defining the protobuf types, state schema, and connection stores; done means all acceptance criteria are met and downstream handlers can compile against the new types.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- backend-api-design, databases, distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100