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

CLPR-1.1: Define wire formats, state schema, and store implementations for the network layer

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

## 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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.